GS2-Formation

Party and equipment formation feature

It is common to combine the resources you have into a single thing. This is the case when organizing multiple characters into a party, or organizing and equipping items such as weapons and armor.

Forms

To realize the function of equipping characters, multiple slots are provided for weapons, helmets, baskets, bodies, legs, feet, and so on. The character can only be equipped with the items that fit into each slot.

The form model defines which slots exist and which items can be organized in each slot as master data. The actual content of the organization is called a form.

Persisting a Form

There are two ways to store the contents of a form. One is to store the form in a finite number of predefined storage locations, and the other is to store the form as a property of a particular resource in an infinite number of locations.

Mold

Mold is an area for storing a finite number of molds. It is inconvenient to organize a party for each attribute (e.g., fire party, water party, etc.) for each quest. Therefore, you can simplify the process by saving the party you have organized in advance as a form, and then selecting a form from the form when you start a quest.

The number of forms that can be saved in a mold is limited, but this limit can be increased on an individual basis.

PropertyForm

PropertyForm is an area to store forms as properties of a specific resource. It can be used to organize equipment as a property of the possessed character managed in GS2 Inventory.

The equipment of a possessed character is not so much “to persist the contents of the organization in form storage area #1” as “to persist the contents of the organization as a property of character A”. This method should be used because it is more appropriate to “persist the organization as a property of character A” than to “persist the organization as a property of character A”.

Script Triggers

Setting updateMoldScript updateFormScript updatePropertyFormScript in the namespace allows custom scripts to be executed before and after formation data updates. Scripts support both synchronous and asynchronous execution, with asynchronous processing enabling external integration through GS2-Script or Amazon EventBridge.

Main event triggers and script setting names are:

  • updateMoldScript (completion notification: updateMoldDone): before and after Mold updates
  • updateFormScript (completion notification: updateFormDone): before and after Form updates
  • updatePropertyFormScript (completion notification: updatePropertyFormDone): before and after PropertyForm updates

Implementation example

Persistence of composition in Mold

Form Slots can register ItemSets/SimpleItems managed by GS2-Inventory or Entries managed by GS2-Dictionary. To set either of these, a proof-of-ownership signature must be added.

See the description of each service for information on how to obtain a proof-of-ownership signature.

propertyType Types

  • gs2_inventory – Mount ItemSet managed by GS2-Inventory
  • gs2_simple_inventory – Mount SimpleItem managed by GS2-Inventory
  • gs2_dictionary – Mount Entry managed by GS2-Dictionary
    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();

Increasing the Maximum Amount of Form Stored in Mold

The game engine SDK does not support raising the save quantity cap.

Please use GS2-Exchange to raise the rank cap as a reward, for example, by exchanging for charged currency.

Get a list of the contents of the Mold Form

    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());
    }

Get organization details in 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();

Persisting Organization in a Property Form

Form Slots can register ItemSets/SimpleItems managed by GS2-Inventory or Entries managed by GS2-Dictionary. To set each of these, you must add a proof-of-ownership signature.

For information on how to obtain a proof-of-ownership signature, check the description of each service.

    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();

Get the contents of the organization in 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();

Detailed Reference