Manage player inventories using your game client

Last updated on May 13, 2024
note

The Inventory service is currently available as an Early Access feature to AGS Premium clients.

Introduction​

You can integrate the AccelByte Gaming Service (AGS) Inventory service into your game client, giving your players the flexibility to manage their own inventories and items. The Inventory service enables your players to control their items in various aspects in-game, from deciding what can be kept and discarded to organizing and transferring items according to needs and preferences.

This article walks you through how to configure your game client to allow your players to manage their inventories and items.

Prerequisites​

Enable players to retrieve inventory configuration​

Inventory configuration is a set of information and rules set by the admin to determine the type of inventory that the game will support. The configuration consists of the following:

  • code: an ID for the inventory configuration.
  • name: name for the inventory configuration.
  • description: (optional) a brief description or additional information describing the inventory configuration.
  • maxInstancesPerUser: maximum number of inventories that can be owned by a player.
  • initialMaxSlots: maximum number of slots a player can have to store their items. Each slot can store a single non-stackable item or multiple identical items stacked as one.
  • maxUpgradeSlots: maximum number of slots upgrade a player can own in the inventory.

You can use the list of Inventory Configurations to display the available inventories within the game that the player can obtain.

Multiple inventories in AGS

To enable your players to retrieve inventory configuration, use this function:

EAccelByteInventoryConfigurationSortBy SortBy = EAccelByteInventoryConfigurationSortBy::CREATED_AT_DESC;
FString ConfigurationCode = FString("SomeConfigurationCode");

FAccelByteModelsInventoryConfigurationsPagingResponse OutResult;

const FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();
ApiClient->Inventory.GetInventoryConfigurations(
THandler<FAccelByteModelsInventoryConfigurationsPagingResponse>::CreateLambda([&](const FAccelByteModelsInventoryConfigurationsPagingResponse& Result)
{
    OutResult = Result;
    // Do something if GetInventoryConfigurations is successful
})
, FErrorHandler::CreateLambda([&](const int32 ErrorCode, const FString& ErrorMessage)
            {
    // Do something if GetInventoryConfigurations has an error
}) , SortBy, 50, 0, ConfigurationCode);

Enable players to retrieve list of own inventories​

You can allow your players to retrieve a list of their own inventories, which will provide the following information:

  • inventoryConfigurationCode: used to refer to the specific inventory configuration.
  • inventoryConfigurationId: used as the identifier for the inventory.
  • maxSlots: refers to the maximum number of slots the player can use in the inventory.
  • maxUpgradeSlots: refers to the maximum number of slots that can be upgraded by the player in the inventory.
  • usedCountSlots: refers to the number of slots already used by the player.
important

The inventoryConfigurationId is used in various inventory management functions.

You can use the information above to display it to the player. For example:

Display inventories in AGS

To enable players to retrieve a list of their own inventories, use this function:


EAccelByteUserInventoriesSortBy SortBy = EAccelByteUserInventoriesSortBy::CREATED_AT_DESC;
FString ConfigurationCode = FString("SomeConfigurationCode");

FAccelByteModelsUserInventoriesPagingResponse OutResult;

const FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();
ApiClient->Inventory.GetUserInventories(
THandler<FAccelByteModelsUserInventoriesPagingResponse>::CreateLambda([&](const FAccelByteModelsUserInventoriesPagingResponse& Result)
{
    OutResult = Result;
    // Do something if GetUserInventories is successful
})
, FErrorHandler::CreateLambda([&](const int32 ErrorCode, const FString& ErrorMessage)
            {
    // Do something if GetUserInventories has an error
}) , SortBy, 50, 0, ConfigurationCode);

Enable players to retrieve a list of items from their inventory​

You can enable your players to see the items inside a specific inventory and view the following information:

  • qty: number of the same items that can be stacked in a slot.
  • sourceItemId: ID that will be used to look up the items dictionary.
  • slotUsed: number of slots that are being used for the item.
  • slotId: ID of the slot where the item is stored. If it's not specified, the default slot will be filled as default.
  • serverCustomAttributes: additional attributes that only support server-authoritative actions.
  • customAttributes: additional attributes that support both player- and server-authoritative actions.
  • type: refers to the item type, such as in-game item, bundle, loot box, option box, etc.
  • tag: can be used for grouping and categorizing items.
note

The sourceItemId will be used to look up the items dictionary. If you are using AccelByte store, you can fill the sourceItemId with the same itemId from the store.

The following images show sample implementations:

  • Simple implementation

    Display item in AGS

  • Implementation that uses qty, slotUsed, and slotId to flexibly store items

    Display item by slot in AGS

    • You can store a single item in multiple slots by setting the slotUsed field to a specific number. For example, slotUsed: 3 would store one Sword in three slots.

    • You can stack multiple items in a single slot by setting the qty field to a specific number. For example, qty: 99 would store 99 potions in a single slot.

    • You can use slotId to specify which slot to store items in. By default, if you do not specify the slot, it will be filled with default.

      • If you want to let your players store potions in the first slot similar to the second example implementation, set slotId to slotId: "0".
      • If you want to store the same potions in a different slot (for example, the potions stored in the middle row of the first column of the slot similar to the second example implementation), set slotId to slotId: "5"

    • You can enhance the item's dimension and slot position with serverCustomAttributes and customAttributes. In the second example implementation, the sword takes up three slots in column 5.

      "serverCustomAttributes": {
          "slotDimensionHeight": 3,
          "slotDimensionWidth":1,
      },
      "customAttributes": {
          "slotPosition": "[0,4],[1,4],[2,4]"
      }

      The item's dimension is stored in serverCustomAttributes to prevent the player from adjusting the information. This information will be used by the game client to identify the item dimension. For the slot position, you can store it in customAttributes to allow your player to move the item position.

To enable players to retrieve a list of items from their inventory, use this function:

FString InventoryId = FString("SomeInventoryId");
EAccelByteUserItemsSortBy SortBy = EAccelByteUserItemsSortBy::CREATED_AT_DESC;
FString SourceItemId = FString("SomeSourceItemId");
FString Tags = FString("SomeTags");

FAccelByteModelsUserItemsPagingResponse OutResult;

const FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();
ApiClient->Inventory.GetUserInventoryAllItems(InventoryId,
    THandler<FAccelByteModelsUserItemsPagingResponse>::CreateLambda([&](const FAccelByteModelsUserItemsPagingResponse& Result)
     {
         OutResult = Result;
         // Do something if GetUserInventoryAllItems is successful
     })
    , FErrorHandler::CreateLambda([&](const int32 ErrorCode, const FString& ErrorMessage)
     {
         // Do something if GetUserInventoryAllItems has an error
     }), SortBy, 50, 0, SourceItemId, Tags);

Enable players to update item attributes and tags​

You can allow your players to store additional information and tags for the items in their inventory.

Custom attributes​

These attributes are allowed to be updated by the player (via game client) or game server. This is suitable if you want to allow your player to store additional information related to the items. The attribute stored is usually the one that does not impact the gameplay mechanics, for example, item style or cosmetic. This attribute will be stored in the customAttributes field.

Using custom attributes for Inventory Item in AGS

Tags​

You can enable your players to add tags to items for tagging and grouping purposes.

notes
  • Not all tags can be used by the players. Some tags can only be added via the game server. See Update tags via game server.
  • Tags are predefined and only admins can add and modify the predefined tags.

Using tag for inventory item in AGS

Use this function:

FJsonObjectWrapper UpdatedCustomAttributes;
UpdatedCustomAttributes.JsonObject = MakeShared<FJsonObject>();
UpdatedCustomAttributes.JsonObject->SetStringField("SomeAttributeStringKey", "UpdatedAttribute");

FAccelByteModelsUpdateUserInventoryItemRequest UpdateInventoryItemRequest = {};
UpdateInventoryItemRequest.CustomAttributes = UpdatedCustomAttributes;
UpdateInventoryItemRequest.SlotId = FString("SomeUpdatedSlotId");
UpdateInventoryItemRequest.SourceItemId = FString("SomeUpdatedSourceItemId");
UpdateInventoryItemRequest.Tags.Add(FString("SomeUpdatedTags"));

FString InventoryId = FString("SomeInventoryId");

TArray<FAccelByteModelsUpdateUserInventoryItemResponse> OutResult;

const FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();
ApiClient->Inventory.BulkUpdateInventoryItems(InventoryId, { UpdateInventoryItemRequest },
    THandler<TArray<FAccelByteModelsUpdateUserInventoryItemResponse>>::CreateLambda([&](const TArray<FAccelByteModelsUpdateUserInventoryItemResponse>& Result)
     {
         OutResult = Result;
         // Do something if BulkUpdateInventoryItems is successful
     })
    , FErrorHandler::CreateLambda([&](const int32 ErrorCode, const FString& ErrorMessage)
     {
         // Do something if BulkUpdateInventoryItems has an error
     }));

Enable players to retrieve all available tags​

To enable your players retrieve a list of available tags that they can use to tags items in their inventory, use this function:

EAccelByteInventoryUtilitiesSortBy SortBy = EAccelByteInventoryUtilitiesSortBy::CREATED_AT_DESC;

FAccelByteModelsInventoryTagPagingResponse OutResult;

const FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();
ApiClient->Inventory.GetInventoryTags(
    THandler<FAccelByteModelsInventoryTagPagingResponse>::CreateLambda([&](const FAccelByteModelsInventoryTagPagingResponse& Result)
     {
         OutResult = Result;
         // Do something if GetInventoryTags is successful
     })
    , FErrorHandler::CreateLambda([&](const int32 ErrorCode, const FString& ErrorMessage)
     {
         // Do something if GetInventoryTags has an error
     }), SortBy, 50, 0);

Enable players to consume items​

To enable your players to consume the items in their inventories, use this function:


FAccelByteModelsConsumeUserItemsRequest ConsumeItemsRequest = {};
ConsumeItemsRequest.SourceItemId = FString("SomeSourceItemId");
ConsumeItemsRequest.SlotId = FString("SomeSlotId");
ConsumeItemsRequest.Qty = 1;

FString InventoryId = FString("SomeInventoryId");

FAccelByteModelsUserItemResponse OutResult;

const FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();
ApiClient->Inventory.ConsumeUserInventoryItem(InventoryId, { ConsumeItemsRequest },
    THandler<FAccelByteModelsUserItemResponse>::CreateLambda([&](const FAccelByteModelsUserItemResponse& Result)
     {
         OutResult = Result;
         // Do something if ConsumeUserInventoryItem is successful
     })
    , FErrorHandler::CreateLambda([&](const int32 ErrorCode, const FString& ErrorMessage)
     {
         // Do something if ConsumeUserInventoryItem has an error
     }));

Enable players to remove item​

To enable your player to remove items from their inventory, use this function:


FAccelByteModelsDeleteUserInventoryItemsRequest DeleteItemsRequest = {};
DeleteItemsRequest.SourceItemId = FString("SomeSourceItemId");
DeleteItemsRequest.SlotId = FString("SomeSlotId");

FString InventoryId = FString("SomeInventoryId");

TArray<FAccelByteModelsDeleteUserInventoryItemResponse> OutResult;

const FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();
ApiClient->Inventory.BulkDeleteInventoryItems(InventoryId, { DeleteItemsRequest },
    THandler<TArray<FAccelByteModelsDeleteUserInventoryItemResponse>>::CreateLambda([&](const TArray<FAccelByteModelsDeleteUserInventoryItemResponse>& Result)
     {
         OutResult = Result;
         // Do something if BulkDeleteInventoryItems is successful
     })
    , FErrorHandler::CreateLambda([&](const int32 ErrorCode, const FString& ErrorMessage)
     {
         // Do something if BulkDeleteInventoryItems has an error
     }));

Enable players to move items between inventories​

Enable your players to move items between inventories. This gives the the flexibility to manage their items as they prefer and enhances their gameplay and strategic decision-making experience.

Move items between inventories in AGS

Use this function:


FAccelByteModelsMoveUserItemDataRequest MoveItem = {};
MoveItem.Qty = 1;
MoveItem.SlotId = FString("SomeSlotId");
MoveItem.SourceItemId = FString("SomeSourceItemId");

FAccelByteModelsMoveUserItemsBetweenInventoriesRequest MoveItemsRequest = {};
MoveItemsRequest.SrcInventoryId = FString("SomeSourceInventoryId");
MoveItemsRequest.Items.Add(MoveItem);

FString DestinationInventoryId = FString("SomeDestinationInventoryId");

FAccelByteModelsMoveUserItemsBetweenInventoriesResponse OutResult;

const FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();
ApiClient->Inventory.MoveItemsBetweenInventories(DestinationInventoryId, MoveItemsRequest,
    THandler<FAccelByteModelsMoveUserItemsBetweenInventoriesResponse>::CreateLambda([&](const FAccelByteModelsMoveUserItemsBetweenInventoriesResponse& Result)
     {
         OutResult = Result;
         // Do something if MoveItemsBetweenInventories is successful
     })
    , FErrorHandler::CreateLambda([&](const int32 ErrorCode, const FString& ErrorMessage)
     {
         // Do something if MoveItemsBetweenInventories has an error
     }));

Last updated on

On this page