GS2-Formation

パーティ・装備編成機能

所有しているリソースを組み合わせて1つの何かを編成するという仕様は一般的です。複数のキャラクターを編成してパーティを作ったり、武器・防具といったアイテムを編成して装備するといったものです。

フォーム

キャラクターの装備機能を実現するにあたって、武器・兜・籠手・胴・脚・足といった複数のスロットを用意し各スロットに適合するアイテムのみを装備できるように設定が可能です。

Form Model では、どのようなスロットが存在するのか、各スロットにはどのようなアイテムを編成できるのかをマスターデータとして定義します。マスターデータを登録することでマイクロサービスで利用可能なデータや振る舞いを設定できます。

マスターデータの種類には以下があります。

MoldModel: Mold の保存枠構成
PropertyFormModel: PropertyForm のスロット構成

マスターデータの登録はマネージメントコンソールから登録する他、GitHubからデータを反映したり、GS2-Deployを使ってCIから登録するようなワークフローを組むことが可能です。

スクリプトトリガー

ネームスペースに updateMoldScript updateFormScript updatePropertyFormScript を設定すると、編成データの更新前後でカスタムスクリプトを実行できます。スクリプトは同期・非同期の実行方式を選択でき、非同期では GS2-Script や Amazon EventBridge を介した外部連携にも対応します。

設定できる主なイベントトリガーとスクリプト設定名は以下の通りです。

updateMoldScript（完了通知: updateMoldDone）: Mold 更新の前後
updateFormScript（完了通知: updateFormDone）: Form 更新の前後
updatePropertyFormScript（完了通知: updatePropertyFormDone）: PropertyForm 更新の前後

実装例

Mold での編成の永続化

Form の Slot には GS2-Inventory で管理する ItemSet / SimpleItem か、GS2-Dictionary で管理する Entry を登録できます。それぞれ設定するためには、所有証明署名を付加する必要があります。

所有証明署名の取得方法については各サービスの説明を確認してください。

propertyType の種類

gs2_inventory – GS2-Inventory で管理する ItemSet を装着
gs2_simple_inventory – GS2-Inventory で管理する SimpleItem を装着
gs2_dictionary – GS2-Dictionary で管理する Entry を装着

    var result = await gs2.Formation.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Mold(
        moldName: "mold-0001"
    ).Form(
        index: 0
    ).SetFormAsync(
        slots: new [] {
            new Gs2.Unity.Gs2Formation.Model.EzSlotWithSignature
            {
                Name = "slot-0001",
                PropertyType = "gs2_dictionary",
                Body = "body",
                Signature = "signature",
            },
        },
        keyId: "key-0001"
    );

    const auto Domain = Gs2->Formation->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Mold(
        "mold-0001" // moldName
    )->Form(
        0 // index
    );
    const auto Future = Domain->SetForm(
        []
        {
            const auto v = MakeShared<TArray<TSharedPtr<Gs2::Formation::Model::FSlotWithSignature>>>();
            v->Add({'name': 'slot-0001', 'propertyType': 'gs2_dictionary', 'body': 'body', 'signature': 'signature'});
            return v;
        }(),
        "key-0001"
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError()) return false;

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError()) return false;
    const auto Result = Future2->GetTask().Result();

Mold の Form 保存数量上限の引き上げ

保存数量上限の引き上げはゲームエンジン用の SDK では処理できません。

GS2-Exchange で課金通貨との交換などの報酬としてランクキャップを引き上げるようにしてください。

Mold での編成内容の一覧を取得

    var items = await gs2.Formation.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Mold(
        moldName: "mold-0001"
    ).FormsAsync(
    ).ToListAsync();

    const auto Domain = Gs2->Formation->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Mold(
        "mold-0001" // moldName
    );
    const auto It = Domain->Forms(
    );
    TArray<Gs2::UE5::Formation::Model::FEzMoldPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

Mold での編成内容を取得

    var item = await gs2.Formation.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Mold(
        moldName: "mold-0001"
    ).Form(
        index: 0
    ).ModelAsync();

    const auto Domain = Gs2->Formation->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Mold(
        "mold-0001" // moldName
    )->Form(
        0 // index
    );
    const auto item = Domain.Model();

Property Form での編成の永続化

Form の Slot には GS2-Inventory で管理する ItemSet か、GS2-Dictionary で管理する Entry を登録できます。それぞれ設定するためには、所有証明署名を付加する必要があります。

所有証明署名の取得方法については各サービスの説明を確認してください。

    var result = await gs2.Formation.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).PropertyForm(
        formModelName: "form-0001",
        propertyId: "property-0001"
    ).SetPropertyFormAsync(
        slots: new [] {
            new Gs2.Unity.Gs2Formation.Model.EzSlotWithSignature
            {
                Name = "slot-0001",
                PropertyType = "gs2_dictionary",
                Body = "body",
                Signature = "signature",
            },
        },
        keyId: "key-0001"
    );

    const auto Domain = Gs2->Formation->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->PropertyForm(
        "form-0001", // formModelName
        "property-0001" // propertyId
    );
    const auto Future = Domain->SetPropertyForm(
        []
        {
            const auto v = MakeShared<TArray<TSharedPtr<Gs2::Formation::Model::FSlotWithSignature>>>();
            v->Add({'name': 'slot-0001', 'propertyType': 'gs2_dictionary', 'body': 'body', 'signature': 'signature'});
            return v;
        }(),
        "key-0001"
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError()) return false;

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError()) return false;
    const auto Result = Future2->GetTask().Result();

Property Form での編成内容を取得

    var item = await gs2.Formation.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).PropertyForm(
        formModelName: "form-0001",
        propertyId: "property-0001"
    ).ModelAsync();

    const auto Domain = Gs2->Formation->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->PropertyForm(
        "form-0001", // formModelName
        "property-0001" // propertyId
    );
    const auto item = Domain.Model();

詳細なリファレンス

APIリファレンス