GS2-Dictionary

Dictionary function

GS2-Dictionary provides a dictionary function for items and characters acquired in the game.

Basically, it can be seen as a simple implementation of GS2-Inventory, which allows you to manage the ownership status of acquired or unacquired binary values.

It can also be used for purposes other than an dictionary. For example, the ownership status of avatar parts is a good example. It is sufficient to manage the possession status of avatar parts by binary value for each part, so it is suitable for GS2 dictionary.

However, if you have a specification that allows you to sell unwanted parts, GS2-Dictionary cannot handle it because it does not allow you to delete entries. You must use GS2-Inventory and GS2-Dictionary according to the specifications your game requires.

Difference from GS2-Inventory

Need stack concept?

GS2-Inventory has the concept of stacking when multiple copies of the same item are held. This means that up to 99 potions can be stacked, and a second stack is created when the number of potions exceeds 99.

Because of this specification, in GS2 Inventory, the return value of the API for “Get number of potions held” is a list. This is because there can be multiple stacks of potions. This specification is convenient for managing data such as potions, but it is over-specified for managing simple possession states such as the dictionary, and handling lists increases the amount of code written.

Multiple entries can be registered in the acquisition process

GS2-Inventory requires that potions and elixirs be registered in separate API requests. GS2-Dictionary can register up to 10 entries in a single API request.

Example implementation

Recording in the dictionary

Recording entries in the dictionary cannot be handled by the game engine SDK.

You must perform the recording process by setting a reward to record monsters defeated as a reward for completing the GS2 quest, or by setting a reward to record items purchased in the GS2 Showcase.

Obtaining a list of master data that can be recorded in the dictionary

Master data must be uploaded to GS2 in advance. There is a separate section on how to manage master data for handling master data, so please refer there.

    var items = await gs2.Dictionary.Namespace(
        namespaceName: "namespace-0001"
    ).EntryModelsAsync(
    ).ToListAsync();
    const auto Domain = Gs2->Dictionary->Namespace(
        "namespace-0001" // namespaceName
    );
    const auto It = Domain->EntryModels(
    );
    TArray<Gs2::UE5::Dictionary::Model::FEzEntryModelPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

Obtaining a list of entries recorded in the directory

    var items = await gs2.Dictionary.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).EntriesAsync(
    ).ToListAsync();
    const auto Domain = Gs2->Dictionary->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    );
    const auto It = Domain->Entries(
    );
    for (auto Item : *It)
    {

    }

Obtaining a Possessive Certification Signature

When interfacing with other microservices within GS2, you may be asked for data that guarantees that the entry has indeed been recorded in GS2-Dictionary.

For example, suppose that GS2-Dictionary manages the possession state of avatar parts, and GS2-Formation manages the organization state of avatar parts. You would make an API request to GS2-Formation to set the “hair-0001” part when you set the hairstyle in GS2-Formation, but GS2-Formation will request that “hair-0001” be specified along with the possession certificate signature.

This eliminates the need for GS2-Formation to communicate with GS2-Dictionary behind the scenes to determine if the part is really owned.

    var result = await gs2.Dictionary.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Entry(
        entryModelName: "entry-0001"
    ).GetEntryWithSignatureAsync(
        keyId: "grn:gs2:{region}:{yourOwnerId}:key:namespace-0001:key:key-0001"
    );

    var body = result.Body;
    var signature = result.Signature;
    const auto Domain = Gs2->Dictionary->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Entry(
        "entry-0001" // entryModelName
    );
    const auto Future = Domain->GetEntryWithSignature(
        "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();
    const auto Body = Result->Body;
    const auto Signature = Result->Signature;

Detailed Reference