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 implement character equipment functionality, multiple slots such as weapons, helmets, gauntlets, torsos, legs, and feet are prepared. It is possible to configure settings so that only items compatible with each slot can be equipped.

In Form Model, the types of slots that exist and the types of items that can be configured for each slot are defined as master data. Registering master data allows you to configure data and behaviors available for use in microservices.

The types of master data include the following:

  • MoldModel: Mold storage slot configuration
  • PropertyFormModel: PropertyForm slot configuration

Master data can be registered via the Management Console. Additionally, workflows can be set up to reflect data from GitHub or register via CI using GS2-Deploy.

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

Transaction Actions

GS2-Formation provides the following transaction actions:

  • Verify Action: Verify capacity (maximum storage quantity)
  • Consume Action: Subtract capacity
  • Acquire Action: Add capacity, set capacity, set formation (Form / PropertyForm), apply acquire actions to organized resources

By using “Apply acquire actions to organized resources” as an acquire action, it is possible to perform processes such as directly adding experience points to a character organized in a specific party slot. Additionally, by setting “Add capacity” as a reward, it is possible to automatically expand formation slots upon achieving a specific mission.

Implementation example

Persisting formation 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 Mold Capacity

Increasing capacity (maximum storage quantity) cannot be handled via the SDK for game engines.

Please use GS2-Exchange to increase capacity as a reward, such as through exchange with premium currency.

Get a list of formation contents in 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());
    }

Get formation content 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 formation in Property Form

Form Slots can register ItemSets 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 formation content 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();

Resource Management and Notes

Specifying Properties

Properties to be placed in formation slots are specified by property ID. By setting a regular expression for property IDs in the slot model configuration, you can restrict which values can be assigned to that slot.

Proof-of-Ownership Signatures and Post-Formation Caveats

When setting items managed by GS2-Inventory to a slot, you can specify the formation target using a signed item set (proof-of-ownership signature) issued by GS2-Inventory. The ownership guarantee provided by the signed item set is valid only at the time of composition. If the item is subsequently sold or consumed, the formation data remains unchanged. Therefore, when consuming or selling an item in GS2-Inventory, you must first verify — in the client or a script — that the item is not currently in use in a GS2-Formation slot.

Preventing Deletion of Items in Formation via ItemSet.referenceOf

When using Standard Inventory (GS2-Inventory), you can prevent accidental consumption or deletion of items that are currently in formation by using the referenceOf field on ItemSet.

When placing an item into a formation slot, set a string that identifies the slot (e.g., a GRN) in ItemSet.referenceOf. The Inventory Model settings in Standard Inventory include an option to “prohibit consumption when referenceOf is set”. When this option is enabled, any item whose ItemSet.referenceOf is non-empty cannot be consumed or sold, effectively locking the item at the system level while it is in use in a formation.

Detailed Reference

Reference of GS2-Formation