Modelo do dispositivo Transações na Ilha

O dispositivo em Verse Transações na Ilha contém um modelo para transações na ilha. Ele vem com todas as implementações para os principais aspectos do módulo Loja, na API Verse. Inclui itens, ofertas, ofertas de pacotão e o gerenciamento de compras fazendo uso da interface padrão da loja. Use este código como guia para configurar rapidamente sua loja.

Para acessar o dispositivo:

• Acesse o Explorador do Verse.

• Clique com o botão direito no nome do seu projeto.

• Selecione "Adicionar novo arquivo Verse ao projeto".

• Selecione o dispositivo Transações na Ilha.

Como criar itens

Em Verse, temos itens que se dividem em duas categorias: consumíveis, que são removidos do inventário de jogo ao serem usados; e duráveis, que podem ser usados sem que sejam removidos do inventário.

O módulo EntitlementInfo

Módulos são unidades atômicas de código que podem ser redistribuídas para uso em mais de um arquivo. Os módulos podem ser alterados com o tempo sem desfazer as dependências em um arquivo em que o módulo já esteja sendo usado. Você pode separar unidades de código extensas ou repetitivas, como definições de itens, em um arquivo distinto e, em seguida, importá-las com a declaração de uso.

O módulo EntitlementInfo reúne os nomes, as descrições e as descrições curtas de todos os itens no modelo. Inclua este módulo em qualquer arquivo no qual você precise definir itens sem precisar redefinir o nome e outras variáveis repetidamente para o mesmo produto, o que torna as alterações nas informações de itens mais simples e reduz a complexidade da depuração de seus itens.

# Setup your entitlements and offers data, in this case that's your Names, Descriptions & Short Descriptions as well as any other data you want to be constant

EntitlementInfo<public> := module:

    Potion<public> := module:

        Name<public><localizes>:message = "Potion"

        Description<public><localizes>:message = "Adds +10 health when used. Green so you know its healthy!"

Como definir itens

Cada item em Verse tem as seguintes propriedades:

• Name: o nome do item com até 50 caracteres.

• Description: a descrição longa exibida com o item, com até 500 caracteres.

• ShortDescription: uma descrição curta de até 100 caracteres que resume o item.

• Icon: uma imagem do item.

Os itens em Verse também podem ter as seguintes propriedades opcionais:

• MaxCount: a quantidade máxima desse item que é possível ter ao mesmo tempo.

• Consumable: se este elemento for definido como true, o item poderá ser consumido com ConsumeEntitlement, diminuindo a quantidade total do item consumido que temos nos sistemas da Epic. Se for false, o item será permanente e não será consumido ao ser usado.

• PaidArea: se for definido como true, o item permite entrar em uma área com acesso pago.

• PaidRandomItem: se for definido como true, esses itens são comprados ou resgatados com conteúdo para se obter uma recompensa aleatória.

• ConsequentialToGameplay: se este elemento estiver definido como true, o item concede uma vantagem importante na sua ilha. Consulte mais informações em Consequente para jogabilidade.

No trecho de código abaixo, você usa o módulo EntitlementInfo definido anteriormente para criar as definições dos seus itens. Para definir um item consumível, Consumable deve ser definido como true.

Antes de definir seus itens, você precisa criar uma classe de item base que será usada para os itens na sua experiência;  neste caso, feature_example_entitlement.

Você também precisa definir um caminho de arquivo para uma textura de ícone para cada definição de item ou a definição do seu item não passará na validação.

Entitlements<public> := module:
    using {EntitlementInfo}

    # The base entitlement you should define for ALL your entitlements in your experience

    feature_example_entitlement<public> := class<abstract><castable>(entitlement){}

    basic_sword<public> := class<concrete>(feature_example_entitlement):

        var Name<override>:message = Sword.Name

Ofertas de itens

Na oferta, os itens ou ativos têm um preço especificado em V-Bucks. Cada oferta tem um nome, descrição e ícone separados das especificações do item. Ofertas são definidas em Verse.

Para vender o item, você precisa ter uma oferta correspondente para ele.

Cada oferta tem as seguintes propriedades:

• Name: o nome da oferta.

• Description: a descrição longa exibida juntamente com a oferta.

• ShortDescription: uma descrição curta que resume a oferta em caixas de diálogo menores.

• Icon: a imagem da oferta.

• EntitlementType: uma declaração do item incluído na oferta.

• Price: o valor em V-Bucks. Não pode ser menor que 50 V-Bucks, nem maior que 5.000 V-Bucks. O preço deve ser definido em múltiplos de 50.

Este trecho de código demonstra como definir as ofertas de itens, usando seu módulo EntitlementInfo existente para obter informações básicas de ofertas de itens. Você também precisa definir um ícone, o EntitlementType;  que define o item ao qual a oferta se refere, e o valor em V-Bucks. Também é possível definir uma idade mínima opcional de compra para uma oferta, considerando um valor fixo, um código de país ou restringir o acesso à oferta por família de plataformas ou uma combinação desses fatores. Alguns exemplos disso são demonstrados no trecho de código abaixo.

ExampleOffers<public> := module:
    using {EntitlementInfo}

    basic_sword<public> := class(entitlement_offer):

        var Name<override>:message                = EntitlementInfo.Sword.Name

        var Description<override>:message         = EntitlementInfo.Sword.Description

        var ShortDescription<override>:message    = EntitlementInfo.Sword.ShortDescription

Para obter mais informações, consulte Restrições de Transações na Ilha.

 Ofertas de pacotão

Pacotões são definidos em Verse e podem apresentar uma combinação de ofertas diferentes, a mesma oferta acumulada, ou uma combinação de ambas. Assim como em ofertas simples, as ofertas de pacotão têm seu próprio preço, nome e descrição especificados, além de um ícone diferente dos ícones de itens e ofertas. Você também pode aninhar ofertas ao incluir pacotões em uma oferta de pacotão. Um exemplo disso seria um pacotão por tempo limitado que inclui uma pá e um pacotão de sementes de milho. Assim você pode usar pacotões menores para montar pacotões maiores combinando itens.

Os tipos de pacotão padrão são:

• Pacotão acumulado: um pacotão que contém várias ofertas do mesmo item, geralmente com desconto.

• Pacotão multioferta: um pacotão que combina ofertas de vários itens, também pode incluir uma combinação de ofertas acumuladas e comuns.

Um pacotão contém uma matriz de tuplas de ofertas, que contém a oferta definida e um número inteiro (int) que indica o número de ofertas.

O trecho de código abaixo demonstra a construção de um pacotão de poções. As informações da oferta são definidas no módulo EntitlementInfo, e incluem a variável PotionCount. 

ExampleOffers<public> := module:

    using {EntitlementInfo}

<# --- other offer definitions above --- #>

    potion_pack<public> := class(bundle_offer) :

        var Name<override>:message                = EntitlementInfo.PotionPack.Name

Restrições de compra

Você pode restringir as compras de itens para permitir a criação de itens limitados de datas festivas, ofertas promocionais ou sazonais e criar conteúdo específico para cada região.

GetMinPurchaseAge

Use GetMinPurchaseAge para definir uma restrição de compra personalizada para uma entitlement_offer específica. Ela é chamada automaticamente como parte da validação de compra e, portanto, exige apenas uma definição. Você pode definir um valor inteiro específico, um código de país ou uma família de plataformas.

Abaixo mostramos alguns exemplos da função GetMinPurchaseAge.

# Optional overrideable function you can use to inform Epic systems what the minimum age a player needs to be to purchase this offer

        GetMinPurchaseAge<override>(CountryCode:string, SubdivisionCode:string, PlatformFamily:string)<decides><computes>:int =

            # A Hypothetical example where you only want to sell swords to people who don't live in Antarctica

            CountryCode <> CountryCodes.Antarctica

            return 0

Validação de itens da pessoa jogadora

A validação de itens da pessoa jogadora é uma etapa necessária para garantir que os itens adquiridos pelo público jogador persistam entre sessões. A não validação correta dos itens pode ocasionar problemas como a duplicação ou perda de itens, por exemplo.

Como validar compras anteriores

O trecho de código abaixo mostra uma validação simples de item feita quando alguém entra em uma sessão. Primeiro, ele verifica se a pessoa está registrada no evento OnPurchasesChanged. A seguir, se ainda não estiver registrada, a pessoa que está entrando será registrada. Por fim, um registro é recuperado de todos os itens comprados para essa pessoa usando ValidatePreviousPurchases.

OnPlayerJoin(InPlayer:player):void =

        Subscription := GetEntitlementsChangedEvent(InPlayer, Entitlements.feature_example_entitlement).Subscribe(OnPurchasesChanged)

        if (set EntitlementChangeSubscription[InPlayer] = option{Subscription}):

            Print("Adding entitlement Change Subscription player subscription")

        # On players joining you are likely going to want to run some validation checks to make sure that any data you save

Tratamento das compras

As duas funções principais usadas para gerenciar compras de itens são BuyOffer e OnPurchasesChanged. A primeira função gerencia a lógica para apresentar uma oferta e validar a compra no jogo. A segunda função gerencia a lógica de uma transação ou reembolso bem-sucedido. Os trechos de código abaixo demonstram as duas funções. 

# Base Implementation of how to present players with an offer to purchase in your experience

    TryBuyOffer(Player:player, Offer:entitlement_offer)<suspends>:void =

        Result := BuyOffer(Player, Offer)

        if (Result?):

            # do nothing it should respond in the purchase subscription, see OnPurchasesChanged for details

Como gerenciar consumíveis

Para consumir um item consumível, você deve usar a função ConsumeEntitlement da API Verse da Loja. Quando o consumo for efetivado, você deve gerenciar a lógica do efeito gerado após o consumo. A função Count do item possuído no jogo será reduzida pela contagem Count consumida na função.

O trecho de código abaixo demonstra como um item específico é consumido pela pessoa especificada.

# Base Implementation of how to flag a consumable in your experience as being consumed

    TryConsumeEntitlement(Player:player, Entitlement:concrete_subtype(entitlement), NumberConsuming:int)<suspends>:void =

        Result := ConsumeEntitlement(Player, Entitlement, ?Count := NumberConsuming)

        if (Result?):

            Print("Successfully consumed entitlement!")

Como conceder itens

Ao contrário de comprar um item que exige V-Bucks, você também pode conceder itens ao público jogador com o método GrantEntitlement.

Os casos de uso em potencial para conceder um item incluem itens promocionais, amostras gratuitas de consumíveis e a restauração de itens perdidos devido a bugs ou falhas.

Este trecho de código demonstra um método para conceder itens ao seu público jogador.

# Base Implementation of how to give players a entitlement in your experience without them purchasing it

    TryGrantEntitlement(Player:player, Entitlement:concrete_subtype(entitlement), NumberToGrant:int)<suspends>:void =

        Result := GrantEntitlement(Player, Entitlement, ?Count := NumberToGrant)

        if (Result?):

            Print("Successfully granted a player your entitlement!")

Mostre suas ofertas de itens ao público jogador

O Marketplace module fornece uma interface de usuário de loja integrada para uso em suas ilhas com a função ShowOffersDialog. O trecho de código abaixo demonstra um método para exibir uma loja que mostra ofertas para uma pessoa específica.

# Base Implementation of how to show an array of offers to the player that are available for purchase

    ShowArrayOfOffers(Player:player)<suspends>:void =

        ShowOffersDialog(Player, array{ExampleOffers.basic_sword{}, ExampleOffers.potion{}, ExampleOffers.potion_pack{}, ExampleOffers.potion_thanksgiving{}, ExampleOffers.potion_gib{}})

Código completo

using { /Fortnite.com/Devices }

using { /Fortnite.com/Marketplace }

using { /UnrealEngine.com/Temporary/Diagnostics }

using { /Verse.org/Assets }

using { /Verse.org/Simulation }