Pilhas

O Economy v2 agora está em disponibilidade geral. Para obter suporte e enviar comentários, acesse o Fórum do PlayFab.

O serviço de Inventory do Economy V2 introduz o conceito de pilhas, que pode adicionar maior flexibilidade e suporte às suas necessidades de inventário. As pilhas permitem que instâncias separadas e distintas do mesmo item existam no mesmo inventário. Esse recurso possibilita cenários de organização no jogo, a capacidade de definir propriedades de item diferentes e muito mais! Itens com o mesmo Id podem ser armazenados como pilhas do item, cada uma com sua própria quantidade e diferenciada por StackId. Se não for especificado, as ações de inventário normalmente usarão a pilha padrão com o StackId: default A pilha padrão pode ser excluída. Na próxima vez que ocorrer uma adição/transferência sem um StackId (ou usando o StackId padrão), a pilha padrão será recriada

Gerenciando inventários e pilhas

A seguir, há um detalhamento das APIs de Inventory e de suas interações com as pilhas.

Adicionar itens de inventário

Na API AddInventoryItems, você pode definir um StackId no parâmetro Item. Esse parâmetro define a pilha que está sendo aumentada ou a ID da nova pilha que está sendo criada. Um exemplo de solicitação AddInventoryItems com um StackId:

{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
        "StackId": "NewStack"
    },
    "Amount": 5,
}

A solicitação acima criaria uma pilha totalmente nova do item com quantidade 5 e StackId NewStack ou adicionaria 5 à NewStack existente, caso ela já existisse

Subtrair itens de inventário

Na API SubtractInventoryItems, o StackId é usado para definir de qual pilha a quantidade será subtraída. Além disso, há um booliano DeleteEmptyStacks que pode ser definido para excluir a pilha caso a quantidade subtraída deixe a pilha com quantidade 0. Tentar subtrair de uma pilha mais do que a quantidade atual da pilha gerará um erro. Um exemplo de solicitação SubtractInventoryItems com StackId:

{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
        "StackId": "NewStack"
    },
    "Amount": 5,
    "DeleteEmptyStacks": true,
}

A solicitação acima subtrairia 5 da pilha com a ID NewStack e excluiria a pilha se ela tivesse exatamente a quantidade 5.

Atualizar itens de inventário

Na API UpdateInventoryItems, você pode definir um StackId no parâmetro Item. Esse parâmetro define a pilha que está sendo atualizada ou a ID da nova pilha que está sendo criada. Um exemplo de solicitação UpdateInventoryItems:

{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
        "StackId": "NewStack",
        "Amount": 5
    }
}

A solicitação acima criaria uma pilha totalmente nova do item com quantidade 5 e StackId NewStack ou definiria a quantidade de NewStack como 5, caso ela já existisse

Excluir itens de inventário

A API DeleteInventoryItems é usada para excluir uma pilha inteira de itens do inventário de um jogador. Um StackId pode ser fornecido para definir a pilha específica do item a ser excluída. Um exemplo de solicitação DeleteInventoryItems:

{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
        "StackId": "NewStack"
    },
}

Comprar itens de inventário

A API PurchaseInventoryItems usa o preço do item definido no catálogo, deduz o custo do inventário do jogador e o troca pela quantidade desejada do item. Você deve especificar o Item que deseja comprar e a Amount do item que deseja comprar. Ao fazer compras com pilhas, há alguns parâmetros relevantes:

Em PriceAmounts, você pode definir um StackId opcional para cada item de preço (ou seja, os itens que estão sendo gastos) para definir de qual pilha os itens gastos serão deduzidos
No objeto Item, você pode definir um StackId opcional que representa a pilha na qual os itens recebidos serão colocados
Há um booliano DeleteEmptyStacks que pode ser definido para excluir a pilha caso a quantidade subtraída deixe a pilha com quantidade 0.

Para obter mais detalhes sobre como comprar itens, consulte PurchaseInventoryItems.

Um exemplo de solicitação PurchaseInventoryItems com pilhas:

{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "LaserSword",
        "StackId": "MyLaserSwordStack"
    },
    "Amount": 10,
    "PriceAmounts": [
        {
            "ItemId": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
            "Amount": 5,
            "StackId": "MyNewStack",
        }
    ],
    "DeleteEmptyStacks": true,
}

Transferir itens de inventário

Ao usar a API TransferInventoryItems com pilhas, há alguns parâmetros relevantes:

No objeto GivingItem, você pode definir um StackId opcional que representa a pilha da qual os itens fornecidos serão retirados
No objeto ReceivingItem, você pode definir um StackId opcional que representa a pilha na qual os itens recebidos serão colocados
Há um booliano DeleteEmptyStacks que pode ser definido para excluir a pilha caso a quantidade de GivingItem deixe a pilha com quantidade 0

Um exemplo de solicitação TransferInventoryItems com pilhas:

{
    "GivingEntity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "ReceivingEntity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "GivingItem": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
        "StackId": "default",
    },
    "ReceivingItem": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
        "StackId": "MyNewStack",
    },
    "Amount": 10,
    "DeleteEmptyStacks": true
}

API ExecuteInventoryOperations

Você pode usar os parâmetros StackId e DeleteEmptyStacks nos objetos Operation da API ExecuteInventoryOperations. Esses parâmetros permitem agrupar várias operações de inventário usando pilhas. Um exemplo de solicitação ExecuteInventoryOperations com pilhas:

"Entity": {
    "Type": "title_player_account",
    "Id": "ABCD12345678"
 },
"Operations": [
    {
        "Update": {
            "Item": {
                "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
                "StackId": "default",
                "Amount": 10
            }
        }
    },
    {
        "Subtract": {
            "Item": {
                "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
                "StackId": "MyNewStack"
            },
            "Amount": 5
        }
    }
]

Adicionando propriedades personalizadas com DisplayProperties e NewStackValues

Você pode definir propriedades de item personalizadas para itens de inventário com o parâmetro DisplayProperties. A definição de propriedades pode ser feita nas APIs AddInventoryItems, PurchaseInventoryItems e TransferInventoryItems, mas somente quando uma nova pilha é criada. Para definir Propriedades de exibição para novos itens, o parâmetro NewStackValues deve ser definido na solicitação de API. Um exemplo de solicitação AddInventoryItems com NewStackValues:

{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "20a645ce-a3bf-4fcb-8e67-36aa7bf0331d",
        "StackId": "NewStack"
    },
    "Amount": 15,
    "NewStackValues": {
        "DisplayProperties": {
            "DifficultyRating":5,
            "IsMagic": true,
            "Rarity": "Legendary"
        }
    }
}

Para atualizar as Propriedades de exibição em itens existentes, a API UpdateInventoryItems pode ser usada para modificar as propriedades diretamente.

XBOX Services

PlayFab

Pilhas de inventário

Pilhas

Gerenciando inventários e pilhas

Adicionar itens de inventário

Subtrair itens de inventário

Atualizar itens de inventário

Excluir itens de inventário

Comprar itens de inventário

Transferir itens de inventário

API ExecuteInventoryOperations

Adicionando propriedades personalizadas com DisplayProperties e NewStackValues

​Pilhas

​Gerenciando inventários e pilhas

​Adicionar itens de inventário

​Subtrair itens de inventário

​Atualizar itens de inventário

​Excluir itens de inventário

​Comprar itens de inventário

​Transferir itens de inventário

​API ExecuteInventoryOperations

​Adicionando propriedades personalizadas com DisplayProperties e NewStackValues

Pilhas

Gerenciando inventários e pilhas

Adicionar itens de inventário

Subtrair itens de inventário

Atualizar itens de inventário

Excluir itens de inventário

Comprar itens de inventário

Transferir itens de inventário

API ExecuteInventoryOperations

Adicionando propriedades personalizadas com DisplayProperties e NewStackValues