Modèle d'appareil Transactions sur l'île

L'appareil Verse Transactions sur l'île contient un modèle pour les transactions sur l'île. Celui-ci inclut toutes les implémentations des principaux aspects du module Marché dans l'API Verse, notamment les objets, les offres, les packs et la gestion des achats via l'IU par défaut de la vitrine. Utilisez ce code comme guide pour configurer rapidement votre vitrine.

Pour accéder à l'appareil :

• Accédez à l'explorateur Verse.

• Faites un clic droit sur le nom de votre projet.

• Sélectionnez Ajouter un nouveau fichier Verse au projet.

• Sélectionnez Appareil Transactions sur l'île.

Créer des objets

Deux catégories d'objets existent dans Verse : les objets à usage unique, qui sont retirés de l'inventaire du joueur une fois utilisés, et les objets durables, que le joueur peut continuer à utiliser sans que l'objet soit retiré de l'inventaire.

Le module EntitlementInfo

Les modules sont des unités atomiques de code que vous pouvez redistribuer pour les utiliser dans plusieurs fichiers. Il est possible de modifier les modules sans rompre les dépendances dans un fichier où le module est déjà utilisé. Vous pouvez placer les unités de code longues ou répétitives, comme les définitions d'objet, dans un fichier distinct, puis importer ce fichier à l'aide de l'instruction d'utilisation.

Le module EntitlementInfo collecte les noms, les descriptions et les descriptions brèves de tous les objets du modèle. Intégrez ce module à n'importe quel fichier dans lequel vous devez définir les objets, sans avoir à redéfinir le nom et d'autres variables à plusieurs reprises pour le même produit, ce qui simplifie les modifications aux informations d'objets et le débogage.

# 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!"

Définir les objets

Chaque objet Verse dispose des propriétés suivantes :

• Nom : le nom de l'objet, qui peut comporter 50 caractères maximum.

• Description : la description détaillée qui s'affiche avec l'objet, pouvant comporter jusqu'à 500 caractères.

• Brève description : résumé de l'objet en 100 caractères maximum.

• Icône : une image de l'objet.

Un objet Verse peut également disposer des propriétés facultatives suivantes :

• Nombre max : le nombre maximal de cet objet que le joueur peut posséder.

• Objet à usage unique : si cette option est activée, l'objet peut être consommé avec ConsumeEntitlement, qui réduit le nombre total d'exemplaires de l'objet consommé dont dispose l'utilisateur dans les systèmes d'Epic. Si cette option est désactivée, l'objet est permanent et ne disparaît pas après utilisation.

• Zone payante : si cette option est activée, l'objet permet d'accéder à une zone soumise à un paiement.

• Objet aléatoire payant : si cette option est activée, ces objets sont achetés ou échangés contre du contenu pour obtenir une récompense aléatoire.

• Incidence sur le jeu : si cette option est activée, l'objet procure un avantage significatif à son détenteur sur votre île. Pour en savoir plus, consultez la rubrique Incidence sur le jeu.

Dans l'extrait de code ci-dessous, vous utilisez le module EntitlementInfo défini précédemment pour créer les définitions de vos objets. Pour définir un objet à usage unique, le paramètre Objet à usage unique doit être activé.

Avant de définir vos objets, vous devez créer une classe d'objets élémentaire qui sera utilisée pour les objets de votre expérience,  ici, feature_example_entitlement.

Vous devez également définir un chemin d'accès à la texture d'icône pour chaque définition d'objet, afin que la définition d'objet soit bien validée.

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

Offres d'objets

Une offre précise le prix en V-bucks d'un objet ou d'une ressource. Chaque offre possède son propre nom, sa propre description et sa propre icône, distincts des spécifications de l'objet. Une offre est définie dans Verse.

Pour vendre un objet, vous devez disposer d'une offre correspondante.

Chaque offre présente les propriétés suivantes :

• Nom : le nom de l'offre.

• Description : la description détaillée qui accompagne l'offre.

• Brève description : résumé de l'offre dans de petites boîtes de dialogue.

• Icône : une image de l'offre.

• Type d'objet : une déclaration de l'objet inclus dans l'offre.

• Prix : un prix, en V-bucks. Le prix doit être compris entre 50 V-bucks et 5 000 V-bucks. Vous devez le définir en multiples de 50.

Cet extrait montre comment définir des offres d'objets en utilisant votre module EntitlementInfo pour des informations de base sur les offres d'objets. Vous devez également définir une icône, l'EntitlementType,  qui définit l'objet de l'offre et le prix en V-bucks. Vous pouvez également définir un âge minimum d'achat pour une offre en fonction d'une valeur fixe ou d'un code de pays, ou restreindre l'accès à l'offre par famille de plateformes (ou une combinaison des trois possibilités). L'extrait de code ci-dessous en donne quelques exemples.

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

Pour en savoir plus, consultez la page Restrictions relatives aux transactions sur l'île.

 Packs d'offres

Les packs sont définis dans Verse et peuvent contenir différentes offres, plusieurs exemplaires de la même offre ou une combinaison des deux. Tout comme les offres simples, les packs comprennent un prix, un nom et une description, et sont accompagnés d'une icône distincte de celle des objets et des offres. Il est également possible d'imbriquer les offres en incluant des lots dans un pack. Par exemple : pack à durée limitée comprenant une pelle et un lot de paquets de semences de maïs. Cela vous permet d'utiliser des packs plus petits comme éléments constitutifs de packs combinés plus volumineux.

Les types de packs standard sont les suivants :

• Pack empilé : pack de plusieurs offres du même objet, généralement à un prix réduit.

• Pack à plusieurs offres : pack combinant des offres pour plusieurs objets, pouvant également inclure une combinaison d'offres empilées et d'offres ordinaires.

Un pack contient une matrice de tuples d'offres, qui contient l'offre définie et un entier indiquant le nombre d'offres.

L'extrait de code ci-dessous montre la construction d'un pack de potions. Les informations de l'offre sont définies dans le module EntitlementInfo et comprennent la variable PotionCount. 

ExampleOffers<public> := module:

    using {EntitlementInfo}

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

    potion_pack<public> := class(bundle_offer) :

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

Restrictions d'achat

Vous pouvez restreindre les achats d'objets afin de créer des offres exceptionnelles, promotionnelles ou saisonnières, et créer du contenu spécifique à une région.

GetMinPurchaseAge

Utilisez GetMinPurchaseAge afin de définir une restriction d'achat personnalisée pour une entitlement_offer spécifique. Appelée automatiquement dans le cadre de la validation de l'achat, elle ne requiert donc qu'une définition. Vous pouvez définir une valeur entière spécifique, un code de pays ou une famille de plateformes.

Voici quelques exemples de la fonction 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

Validation des objets des joueurs

La validation des objets des joueurs est une étape essentielle pour garantir que les objets achetés par les joueurs persistent entre les sessions. L'échec de validation des objets peut entraîner des problèmes, tels que la duplication ou la perte des objets.

Valider les achats précédents

L'extrait de code ci-dessous illustre une validation simple des objets effectuée lorsqu'un joueur rejoint une session. Tout d'abord, il vérifie si le joueur entrant est abonné à l'événement OnPurchasesChanged. Le joueur entrant sera alors abonné s'il ne l'était pas déjà. Enfin, la liste de tous les objets achetés pour ce joueur est récupérée à l'aide de 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

Gérer les achats

Les deux principales fonctions utilisées pour traiter les achats d'objets sont BuyOffer et OnPurchasesChanged. La première fonction gère la logique permettant de présenter une offre au joueur et de valider l'achat. La deuxième fonction gère la logique d'une transaction ou d'un remboursement réussi. Les extraits ci-dessous illustrent ces deux fonctions. 

# 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

Gérer les objets à usage unique

Pour utiliser un objet à usage unique, vous devez utiliser la fonction ConsumeEntitlement de l'API Verse du Marché. Une fois l'objet utilisé, vous devez gérer la logique des conséquences de l'utilisation. Le compte des objets que possède le joueur doit être déduit du compte consommé dans la fonction.

L'extrait de code ci-dessous montre comment un objet spécifique est consommé par un joueur donné.

# 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!")

Attribuer des objets

Contrairement à l'achat d'un objet, qui nécessite des V-Bucks, vous pouvez également attribuer des objets aux joueurs avec la méthode GrantEntitlement.

Parmi les cas d'attribution potentielle d'objet figurent les objets promotionnels, les échantillons gratuits d'objets à usage unique et la restitution d'objets perdus à cause de bogues ou de problèmes techniques.

Cet extrait de code présente une méthode pour attribuer des objets à vos joueurs.

# 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!")

Afficher vos offres d'objets aux joueurs

Le Marketplace module fournit à vos îles une IU de vitrine intégrée comprenant la fonction ShowOffersDialog. L'extrait de code ci-dessous montre une méthode pour afficher une vitrine d'offres à un joueur spécifique.

# 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{}})

Code complet

using { /Fortnite.com/Devices }

using { /Fortnite.com/Marketplace }

using { /UnrealEngine.com/Temporary/Diagnostics }

using { /Verse.org/Assets }

using { /Verse.org/Simulation }