Pular para o conteúdo principal

Inventário do jogador

Requisitos

Para usar o inventário do jogador, você precisa ter um catálogo definido para o seu título. Leia nosso tutorial sobre Catálogos para obter mais informações.
Opcionalmente, você também pode definir lojas para o seu catálogo.
Enquanto um catálogo é a lista de todos os itens disponíveis no jogo, uma loja é um subconjunto de itens do catálogo que tem a opção de preços exclusivos. Várias lojas podem ser definidas por catálogo, para que você possa ter conjuntos distintos de itens para apresentar ao jogador, com base na segmentação de usuários ou em outros fatores. Depois de definir um catálogo pelo Game Manager ou pelas chamadas de API de administrador SetCatalogItems ou UpdateCatalogItems, você poderá usar uma ampla variedade de chamadas da API de inventário no cliente e no servidor.

Visão geral da API

Todas as chamadas da API de inventário foram projetadas para serem autoritativas no servidor e seguras. Quando usadas corretamente, os clientes não conseguirão trapacear nem adquirir itens que não conquistaram. Clientes: Servidor: O exemplo mostrado abaixo ilustra os blocos de código que chamam esses métodos de API e configura casos de uso básicos para o inventário do jogador.
Para referência, esses exemplos vêm do Unicorn Battle, um jogo que criamos como exemplo para demonstrar os recursos do PlayFab.
A moeda virtual AU usada abaixo é o Gold, uma moeda gratuita obtida ao lutar contra monstros (consulte nosso tutorial sobre Moedas). Antes de começarmos, definiremos algumas funções utilitárias que serão usadas e reutilizadas na maioria dos exemplos deste guia.

Exemplo somente do cliente: comprar e consumir uma poção de vida

Ordem das chamadas de API do cliente: PurchaseItem, GetUserInventory, ConsumeItem Primeiro, precisamos começar definindo o item no nosso catálogo. PlayFab - Economia - Editar item do catálogo Veja os requisitos de CatalogItem para a Health Potion.
  • PurchaseItem exige um preço de item positivo (5 AU).
  • ConsumeItem exige que o item seja Consumable, com uma contagem de itens positiva (3).
  • O jogador que faz a compra deve ter cinco AU disponíveis no saldo de moeda virtual.
O código de cada chamada é fornecido abaixo.

Exemplo: o jogador recebe e abre um contêiner

Ordem das chamadas de API: Primeiro, precisamos começar com um contêiner definido no nosso catálogo. Para o nosso contêiner neste exemplo, selecionamos um CrystalContainer. Este exemplo também demonstra a abertura do contêiner com uma chave, um item opcional que também deve estar no inventário do jogador para que a chamada a UnlockContainerInstance tenha êxito. PlayFab - Economia - Editar contêiner do catálogo Os requisitos de CatalogItem para o nosso CrystalContainer neste exemplo incluem:
  • Que o CrystalContainer seja definido como um Container.
  • Que os Containers possam opcionalmente definir um Key Item, que então será necessário para desbloquear o Container; neste caso, um CrystalKey.
  • É altamente recomendável que o seu Container e qualquer Key sejam ambos Consumable, com uma contagem de usos positiva, para que sejam removidos do inventário do jogador após o uso.

Código do servidor

Código do cliente

Consumindo chaves e contêineres

No exemplo anterior, sugere-se que a chave e/ou o contêiner sejam consumíveis, embora isso seja apenas uma recomendação. Mas, se um contêiner e sua chave (se houver) não forem consumíveis, o contêiner poderá ser reaberto infinitamente, concedendo seu conteúdo ao jogador a cada vez. Como a capacidade do inventário do jogador não é infinita, esse padrão é fortemente desencorajado. Quando um contêiner consumível é desbloqueado, tanto o contêiner quanto a chave consumível usada terão automaticamente sua contagem de usos diminuída, sendo removidos do inventário do jogador quando a contagem de usos chegar a zero.

Opções viáveis

Container consumível, sem Key: o padrão mais básico, no qual o contêiner é consumido ao ser aberto e não há chave. Container consumível, Key consumível: o caso simples de contêiner trancado, que permite ao jogador abrir o contêiner com a chave. Ambos são consumidos, e o jogador só pode abrir um contêiner com usos restantes usando uma chave com usos restantes. Container durável, Key consumível: permite que o jogador abra o contêiner sempre que encontrar uma chave. A chave é consumida, e o contêiner só é aberto enquanto a chave tiver usos restantes. Container consumível, Key durável: permite que o jogador mantenha uma chave capaz de abrir todos os contêineres para os quais ela é o item de chave. O contêiner é consumido, mas o jogador mantém a capacidade de abrir contêineres com a chave mais tarde.

Exemplo: comprar itens do inventário do jogador

Não há uma API interna para recomprar itens do inventário do jogador, pois o processo é específico de cada jogo. No entanto, você pode usar os métodos de API existentes para criar sua própria experiência de SellItem:
  • A API de servidor do PlayFab RevokeInventoryItem** permite remover um item do inventário.
  • A API de servidor do PlayFab AddUserVirtualCurrency** pode devolver uma quantidade apropriada de moeda virtual. No momento, não é possível devolver dinheiro real por meio dos métodos de API do PlayFab.
Os itens e as moedas virtuais têm uma relação próxima. Para obter mais informações, consulte nosso tutorial sobre Moedas.
A função do CloudScript a seguir combina as duas chamadas de servidor descritas em uma única chamada acessível pelo cliente.

Práticas recomendadas

  • Verifique se todas as informações de entrada do cliente são válidas antes de fazer qualquer alteração.
  • O CloudScript não é atômico, portanto, a ordem das chamadas importa: AddUserVirtualCurrency pode ter êxito e RevokeInventoryItem pode falhar.
Em geral, é melhor dar ao jogador algo que ele não conquistou nesse processo do que tirar algo dele sem compensação.
Essa função do CloudScript pode então ser acessada a partir do cliente.
Última modificação em 8 de outubro de 2026