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

# Game Engine

GS2-SDK for Game Engine の初期化方法について



## SDK の初期化

GS2 の利用を開始するには、まずは GS2-SDK の初期化処理を行います。
`Gs2Client.Create` を呼び出すことで GS2 のクライアントインスタンスである `Gs2Domain` を取得できます。

初期化に必要なパラメータは以下です。

### パラメータ

| 引数名                      | 型                   | 説明           |
|--------------------------|---------------------|--------------|
| credential               | BasicGs2Credential  | クレデンシャル情報    |
| region                   | Region | 接続先のGS2リージョン |

#### BasicGs2Credential

「クライアントID」と「クライアントシークレット」を指定します。
これらの値は GS2-Identifier で管理しています。

#### Region

GS2 のデータセンターを指定します。
指定可能な値については [リージョン]() を参照してください。

### 実装例



**Unity (UniTask)**
```csharp

    var gs2 = await Gs2.Unity.Core.Gs2Client.CreateAsync(
        new Gs2.Core.Model.BasicGs2Credential(
            "your client id",
            "your client secret"
        ),
        Gs2.Core.Model.Region.ApNortheast1
    );
```
**Unity (Vanilla)**
```cs

    var future = Gs2.Unity.Core.Gs2Client.CreateFuture(
        new Gs2.Core.Model.BasicGs2Credential(
            "your client id",
            "your client secret"
        ),
        Gs2.Core.Model.Region.ApNortheast1
    );
    yield return future;
    if (future.Error != null) {
        throw future.Error;
    }
    var gs2 = future.Result;
```
**Unreal Engine 5**
```cpp

    const auto future = Gs2::UE5::Core::FGs2Client::Create(
        MakeShared<Gs2::Core::Model::FBasicGs2Credential>(
            "your client id",
            "your client secret"
        ),
        Gs2::Core::Model::ApNorthEast1
    );
    future->StartSynchronousTask();
    if (future->GetTask().IsError())
    {
        UE_LOG(GameLog, Error, TEXT("%s"), ToCStr(future->GetTask().Error()->String()));
        return future->GetTask().Error();
    }
    const auto Gs2 = future->GetTask().Result();
```


#### カオスモード

カオスモードを適用したSDK初期化処理を呼び出すことで、APIリクエストを一定の確率で失敗させることができます。
カオスモードを有効にしたクライアントを使用して開発を進めることで、エラーハンドリングを強固なものにすることができます。



**Unity (UniTask)**
```csharp

    var gs2 = await Gs2.Unity.Core.Gs2Client.CreateChaosAsync(
        new Gs2.Core.Model.BasicGs2Credential(
            "your client id",
            "your client secret"
        ),
        0.1f, // APIリクエスト時に10%の確率でリトライが必要なエラーを発生させる
        Gs2.Core.Model.Region.ApNortheast1
    );
```
**Unity (Vanilla)**
```cs

    var future = Gs2.Unity.Core.Gs2Client.CreateChaosFuture(
        new Gs2.Core.Model.BasicGs2Credential(
            "your client id",
            "your client secret"
        ),
        0.1f, // APIリクエスト時に10%の確率でリトライが必要なエラーを発生させる
        Gs2.Core.Model.Region.ApNortheast1
    );
    yield return future;
    if (future.Error != null) {
        throw future.Error;
    }
    var gs2 = future.Result;
```
**Unreal Engine 5**
```cpp

    const auto future = Gs2::UE5::Core::FGs2Client::CreateChaos(
        MakeShared<Gs2::Core::Model::FBasicGs2Credential>(
            "your client id",
            "your client secret"
        ),
        0.1f, // APIリクエスト時に10%の確率でリトライが必要なエラーを発生させる
        Gs2::Core::Model::ApNorthEast1
    );
    future->StartSynchronousTask();
    if (future->GetTask().IsError())
    {
        UE_LOG(GameLog, Error, TEXT("%s"), ToCStr(future->GetTask().Error()->String()));
        return future->GetTask().Error();
    }
    const auto Gs2 = future->GetTask().Result();
```


## アカウントの作成

GS2 の多くの機能はプレイヤーの GS2-Account のアカウント情報を指定してログインする必要があります。
ログインをするためにはアカウントの作成が必要です。

アカウントを作成するには `Gs2Domain::Account::Namespace()::Create` を使用します。

### パラメーター

| 引数名           | 型  | 説明                    |
|---------------|----|-----------------------|
| namespaceName | string | GS2-Account のネームスペース名 |

### 実装例



**Unity (UniTask)**
```csharp

    var account = await (
        await gs2.Account.Namespace(
            this.accountNamespaceName
        ).CreateAsync()
    ).ModelAsync();

    var userId = account.UserId;
    var password = account.Password;
```
**Unity (Vanilla)**
```cs

    var future = gs2.Account.Namespace(
        this.accountNamespaceName
    ).CreateFuture();
    yield return future;
    if (future.Error != null) {
        throw future.Error;
    }
    var future2 = future.Result.ModelFuture();
    yield return future2;
    if (future2.Error != null) {
        throw future2.Error;
    }
    var account = future2.Result;

    var userId = account.UserId;
    var password = account.Password;
```
**Unreal Engine 5**
```cpp

    const auto CreateFuture = Gs2->Account->Namespace(
        AccountNamespaceName
    )->Create();
    CreateFuture->StartSynchronousTask();
    if (CreateFuture->GetTask().IsError())
    {
        UE_LOG(GameLog, Error, TEXT("%s"), ToCStr(CreateFuture->GetTask().Error()->String()));
        return CreateFuture->GetTask().Error();
    }

    const auto LoadFuture = CreateFuture->GetTask().Result()->Model();
    LoadFuture->StartSynchronousTask();
    if (LoadFuture->GetTask().IsError())
    {
        UE_LOG(GameLog, Error, TEXT("%s"), ToCStr(LoadFuture->GetTask().Error()->String()));
        return LoadFuture->GetTask().Error();
    }
    const auto Account = LoadFuture->GetTask().Result();

    auto UserId = Account->GetUserId();
    auto Password = Account->GetPassword();
```


## ログイン

SDK の初期化と、アカウントの作成が終わったことで、ログインができる準備が整います。
`Gs2Domain::Login` を使用することで、ログインを実行できます。

結果として GameSession オブジェクトを取得できます。
多くのAPIは GameSession を渡す必要があり、これによってログイン中のプレイヤーのユーザーデータにアクセスできます。

### パラメーター

| 引数名           | 型              | 説明                       |
|---------------|----------------|--------------------------|
| authenticator | IAuthenticator | 認証処理に使用する実装(GS2-Account) |
| userId        | string         | ユーザーID                   |
| password      | string         | パスワード                    |

#### IAuthenticator

認証処理はインターフェース定義されており、GS2-Account を使用せずに自社の認証基盤での認証に差し替えるような実装が可能です。

#### Gs2AccountAuthenticator

Gs2AccountAuthenticator は、一般的なユースケースにおいて十分な機能を備えた、GS2-Account を用いた認証実装です。

| 引数名            | 型              | 説明                            |
|----------------|----------------|-------------------------------|
| accountSetting | AccountSetting | GS2-Account で認証するための情報        |
| gatewaySetting | GatewaySetting | GS2-Gateway で通知を受け取るための情報     |
| versionSetting | VersionSetting | GS2-Version でバージョンチェックするための情報 |

#### AccountSetting

| 引数名                  | 型              | 説明                                             |
|----------------------|----------------|------------------------------------------------|
| accountNamespaceName | string         | GS2-Account のネームスペース名                          |
| keyId                | string | 認証処理に使用する GS2-Key の暗号鍵ID(省略するとデフォルト暗号鍵が使用されます) |

#### GatewaySetting

| 引数名                  | 型      | 説明                                              |
|----------------------|--------|-------------------------------------------------|
| gatewayNamespaceName | string | GS2-Gateway のネームスペース名(省略するとデフォルトネームスペースが使用されます) |
| allowConcurrentAccess                | bool     | 同一ユーザーIDでの多重ログインを許容するか(デフォルト:true)              |

#### VersionSetting

VersionSetting を適用することで、ログイン時やセッション再接続時に自動的に GS2-Version を使用したバージョンチェックを行うようにできます。
バージョンチェックの結果、エラーが発生すると、 `Gs2AccountAuthenticator::onDetectVersionUp` に登録したイベントハンドラが呼び出されます。

| 引数名                  | 型      | 説明                                         |
|----------------------|--------|--------------------------------------------|
| versionNamespaceName | string | GS2-Version のネームスペース名(省略するとバージョンチェックをしません) |
| targetVersions                | EzTargetVersion[]     | ゲームのバージョン情報                                |

### 実装例



**Unity (UniTask)**
```csharp

    var gameSession = await gs2.LoginAsync(
        new Gs2AccountAuthenticator(
            accountSetting: new AccountSetting {
                accountNamespaceName = this.accountNamespaceName,
            }
        ),
        account.UserId,
        account.Password
    );
```
**Unity (Vanilla)**
```cs

    var future = gs2.LoginFuture(
        new Gs2AccountAuthenticator(
            accountSetting: new AccountSetting {
                accountNamespaceName = this.accountNamespaceName,
            }
        ),
        account.UserId,
        account.Password
    );
    yield return future;
    if (future.Error != null) {
        throw future.Error;
    }
    var gameSession = future.Result;
```
**Unreal Engine 5**
```cpp

    const auto LoginFuture = Gs2->Login(
        MakeShareable<Gs2::UE5::Util::IAuthenticator>(
            new Gs2::UE5::Util::FGs2AccountAuthenticator(
                MakeShared<Gs2::UE5::Util::FAccountSetting>(
                    AccountNamespaceName
                )
            )
        ),
        *Account->GetUserId(),
        *Account->GetPassword()
    );
    LoginFuture->StartSynchronousTask();
    if (LoginFuture->GetTask().IsError())
    {
        UE_LOG(GameLog, Error, TEXT("%s"), ToCStr(LoginFuture->GetTask().Error()->String()));
        return LoginFuture->GetTask().Error();
    }
    const auto GameSession = LoginFuture->GetTask().Result();
```