Manage player inventories using your game server

Last updated on October 24, 2024
note

The Inventory service is available upon request. To integrate this service into your environment, please open a request through the AccelByte Customer Support Portal.

Overview​

The AccelByte Gaming Service (AGS) Inventory service allows you to manage players inventory and items directly from the game server, enabling inventory and items management, organization, or manipulation.

This article lists how you can enable your game server to manage the inventories owned by your players.

Prerequisites​

  • Access to the AGS Admin Portal.

  • A publisher or a game namespace.

  • You have reviewed the key concepts of the Inventory service and the Inventory service API documentation.

  • You have integrated the AccelByte SDK into your game, including the following permissions:

    • Client ID

    • Client Secret

      note

      Support for Unreal and Unity SDKs is currently in development and will be available at a later date. In the meantime, we encourage you to utilize our Extend SDK for all your game server-related actions.

Grant inventory to the player​

You can use this action if you want to allow your game server to grant inventories to players after they reach an achievement or complete a specific action within the game, for example, granting new inventory after a player achieved level 20.

You can enable the game server to grant a new inventory to the player as long as the number of inventory with the same code does not exceed the "maxInstancesPerUser" set in the inventory configuration.

Use this function for reference:

adminInventoriesService := &inventory.AdminInventoriesService{
    Client:          factory.NewInventoryClient(&repository.ConfigRepositoryImpl{}),
    TokenRepository: &repository.TokenRepositoryImpl{},
}
inventoryConfigurationCode := "someConfigurationCode"
userId := "userId"
body := &inventoryclientmodels.ApimodelsCreateInventoryReq {
    InventoryConfigurationCode: &inventoryConfigurationCode,
    UserID: &userId,
}
namespace := "gameNamespace"
input := &admin_inventories.AdminCreateInventoryParams{
    Body:      body,
    Namespace: namespace,
}
result, err := adminInventoriesService.AdminCreateInventoryShort(input)

Retrieve list of player inventories​

Retrieving a list of player inventories can give you information about a player's inventory, such as the inventoryId and inventoryConfigurationId.

To retrieve a list of player inventories via your game server, use this function for reference:

adminInventoriesService := &inventory.AdminInventoriesService{
    Client:          factory.NewInventoryClient(&repository.ConfigRepositoryImpl{}),
    TokenRepository: &repository.TokenRepositoryImpl{},
}
namespace := "gameNamespace"
inventoryConfigurationCode := "SomeConfigurationCode"
limit := int64(10)
offset := int64(0)
sortBy := admin_inventories.AdminListInventoriesCreatedAtConstant
userId, _ := cmd.Flags().GetString("userId")
input := &admin_inventories.AdminListInventoriesParams{
    Namespace:                  namespace,
    InventoryConfigurationCode: &inventoryConfigurationCode,
    Limit:                      &limit,
    Offset:                     &offset,
    SortBy:                     &sortBy,
    UserID:                     &userId,
}
result, err := adminInventoriesService.AdminListInventoriesShort(input)

Update player inventory slot limit​

Use this action to update a specific player's inventory maximum slot limit by providing the inventory ID and the new number of slots that will be implemented.

To update a player's inventory slot limit via your game server, use this function for reference:

adminInventoriesService := &inventory.AdminInventoriesService{
    Client:          factory.NewInventoryClient(&repository.ConfigRepositoryImpl{}),
    TokenRepository: &repository.TokenRepositoryImpl{},
}
incMaxSlots := int32(10)
body := &inventoryclientmodels.ApimodelsUpdateInventoryReq {
    IncMaxSlots: &incMaxSlots,
}
inventoryId := "inventoryId"
namespace := "gameNamespace"
input := &admin_inventories.AdminUpdateInventoryParams{
    Body:        body,
    InventoryID: inventoryId,
    Namespace:   namespace,
}
result, err := adminInventoriesService.AdminUpdateInventoryShort(input)

Delete player inventory​

Player inventories can only be deleted if they're empty. Ensure that you first remove all the items from a player's inventory before deleting it.

To delete a player's inventory via your game server, use this function for reference:

adminInventoriesService := &inventory.AdminInventoriesService{
    Client:          factory.NewInventoryClient(&repository.ConfigRepositoryImpl{}),
    TokenRepository: &repository.TokenRepositoryImpl{},
}
message := "message"
body := &inventoryclientmodels.ApimodelsDeleteInventoryReq {
    Message: &message,
}
inventoryId := "inventoryId"
namespace := "gameNamespace"
input := &admin_inventories.DeleteInventoryParams{
    Body:        body,
    InventoryID: inventoryId,
    Namespace:   namespace,
}
err := adminInventoriesService.DeleteInventoryShort(input)

Add item to player inventory using inventoryId​

Use this action to add items to a player's inventory. This requires you to provide the player's inventoryId, which is information that you can get from retrieving a list of player inventories.

Use this function for reference:

adminItemsService := &inventory.AdminItemsService{
    Client:          factory.NewInventoryClient(&repository.ConfigRepositoryImpl{}),
    TokenRepository: &repository.TokenRepositoryImpl{},
}
slotId := "slot-1"
slotUsed := int32(1)
qty := int32(1)
sourceItemId := "source item id"
type_ := "ingame"
body := &inventoryclientmodels.ApimodelsSaveItemToInventoryReq {
    CustomAttributes: map[string]interface{}{},
    SlotID: &slotId,
    SlotUsed: &slotUsed,
    Qty: &qty,
    ServerCustomAttributes: map[string]interface{}{},
    SourceItemID:&sourceItemId,
    Tags: []string{"weapon"},
    Type: &type_,
}
inventoryId := "inventoryId"
namespace := "gameNamespace"
userId := "userId"
input := &admin_items.AdminSaveItemToInventoryParams{
    Body:        body,
    InventoryID: inventoryId,
    Namespace:   namespace,
    UserID:      userId,
}
result, err := adminItemsService.AdminSaveItemToInventoryShort(input)

Add item to player inventory by inventoryConfigurationCode​

Use this action to add items to a player's specific inventory configuration. This action requires you to provide the inventoryConfigurationCode, which is information that you can get from retrieving a list of player inventories.

Use this function for reference:

adminItemsService := &inventory.AdminItemsService{
    Client:          factory.NewInventoryClient(&repository.ConfigRepositoryImpl{}),
    TokenRepository: &repository.TokenRepositoryImpl{},
}
slotId := "slot-1"
slotUsed := int32(1)
qty := int32(1)
sourceItemId := "source item id"
type_ := "ingame"
body := &inventoryclientmodels.ApimodelsSaveItemReq {
    CustomAttributes: map[string]interface{}{},
    SlotID: &slotId,
    SlotUsed: &slotUsed,
    Qty: &qty,
    ServerCustomAttributes: map[string]interface{}{},
    SourceItemID:&sourceItemId,
    Tags: []string{"weapon"},
    Type: &type_,
}
namespace, _ := cmd.Flags().GetString("namespace")
userId, _ := cmd.Flags().GetString("userId")
input := &admin_items.AdminSaveItemParams{
    Body:      body,
    Namespace: namespace,
    UserID:    userId,
}
result, err := adminItemsService.AdminSaveItemShort(input)

Retrieve list of items from a player's inventory​

Use this function for reference:

adminItemsService := &inventory.AdminItemsService{
    Client:          factory.NewInventoryClient(&repository.ConfigRepositoryImpl{}),
    TokenRepository: &repository.TokenRepositoryImpl{},
}
inventoryId := "inventoryId"
namespace := "gameNamespace"
limit := int64(10)
offset := int64(0)
qtyGte := int64(1)
sortBy := admin_items.AdminListItemsCreatedAtConstant
sourceItemId := "source item ids"
tags := "weapon"
input := &admin_items.AdminListItemsParams{
    InventoryID:  inventoryId,
    Namespace:    namespace,
    Limit:        &limit,
    Offset:       &offset,
    QtyGte:       &qtyGte,
    SortBy:       &sortBy,
    SourceItemID: &sourceItemId,
    Tags:         &tags,
}
result, err := adminItemsService.AdminListItemsShort(input)

Update item attributes and tags​

Unlike the game client, the game server has more ability to add additional attributes and tags.

Update custom attributes​

You can use your game server to update custom attributes written by players and attributes that can only be modified by the server with required permissions. You can use this action to update attributes that will impact gameplay experience, such as item stats modifier. This attribute will be stored in the serverCustomAttributes field, for example, items with additional damage, critical, durability, etc.

Using Server Custom attributes in Inventory item in AGS

Update tags​

You can use your game server to add tags to the items for the purpose of tagging and grouping them. Game servers can add tags to the items and not allow players to update it.

The following image shows a sample item with a tag.

Using tags in Inventory item in AGS

Use this function for reference:

adminItemsService := &inventory.AdminItemsService{
    Client:          factory.NewInventoryClient(&repository.ConfigRepositoryImpl{}),
    TokenRepository: &repository.TokenRepositoryImpl{},
}
slotId := "slot id"
sourceItemId := "sourceItemId"
type_ := "ingame"
item := inventoryclientmodels.ApimodelsAdminUpdateItemReq{
    CustomAttributes: map[string]interface{}{},
    SlotID: &slotId,
    SourceItemID: &sourceItemId,
    ServerCustomAttributes: map[string]interface{}{},
    Tags : []string{"Axe"},
    Type: &type_,
}
body := []*inventoryclientmodels.ApimodelsAdminUpdateItemReq{
    &item,
}
inventoryId := "inventoryId"
namespace := "gameNamespace"
userId := "userId"
input := &admin_items.AdminBulkUpdateMyItemsParams{
    Body:        body,
    InventoryID: inventoryId,
    Namespace:   namespace,
    UserID:      userId,
}
result, err := adminItemsService.AdminBulkUpdateMyItemsShort(input)

Consume items​

To consume items owned by the players via your game server, use this function for reference:

adminItemsService := &inventory.AdminItemsService{
    Client:          factory.NewInventoryClient(&repository.ConfigRepositoryImpl{}),
    TokenRepository: &repository.TokenRepositoryImpl{},
}
qty := int32(1)
slotId := "slotId"
sourceItemId := "sourceItemId"
body := inventoryclientmodels.ApimodelsConsumeItemReq {
    Qty: &qty,
    SlotID: &slotId,
    SourceItemID: &sourceItemId,
}
inventoryId := "inventoryId"
namespace := "gameNamespace"
userId := "userId"
input := &admin_items.AdminConsumeUserItemParams{
    Body:        &body,
    InventoryID: inventoryId,
    Namespace:   namespace,
    UserID:      userId,
}
result, err := adminItemsService.AdminConsumeUserItemShort(input)

Remove items from player's inventory​

To remove items owned by players from their inventory via your game server, use this function for reference:

adminItemsService := &inventory.AdminItemsService{
    Client:          factory.NewInventoryClient(&repository.ConfigRepositoryImpl{}),
    TokenRepository: &repository.TokenRepositoryImpl{},
}
slotId := "slot id"
sourceItemId := "source item id"
item := inventoryclientmodels.ApimodelsRemoveInventoryItemReq {
    SlotID: &slotId,
    SourceItemID: &sourceItemId,
}
body := []*inventoryclientmodels.ApimodelsRemoveInventoryItemReq {
    &item,
}
inventoryId := "inventoryId"
namespace := "gameNamespace"
userId := "userId"
input := &admin_items.AdminBulkRemoveItemsParams{
    Body:        body,
    InventoryID: inventoryId,
    Namespace:   namespace,
    UserID:      userId,
}
result, err := adminItemsService.AdminBulkRemoveItemsShort(input)
Last updated on

On this page