„Käufe auf Inseln“-Gerät-Vorlage

Das „Käufe auf Inseln“-Verse-Gerät enthält eine Vorlage für Käufe auf Inseln. Es verfügt über alle Implementierung von wichtigen Aspekten des Marketplace-Moduls in der Verse-API. Dazu gehören Gegenstände, Angebote, Paketangebote und die Abwicklung von Käufen durch die Nutzung der Standard-Shop-Benutzeroberfläche. Verwende diesen Code, um schnell deinen eigenen Shop zu erstellen.

So greifst du auf das Gerät zu:

• Gehe zum Verse-Explorer.

• Klicke mit der rechten Maustaste auf deinen Projektnamen.

• Wähle „Neue Verse-Datei zum Projekt hinzufügen“ aus.

• Wähle „‚Käufe auf Inseln‘-Gerät“ aus.

Gegenstände erstellen

Gegenstände werden in Verse als Inhalte definiert und fallen jeweils in eine von zwei Kategorien: Verbrauchsgegenstände, die bei Nutzung aus dem Spielerinventar entfernt werden, und dauerhafte Gegenstände, die der Spieler weiterhin verwenden kann, ohne dass sie aus dem Inventar entfernt werden.

Das EntitlementInfo-Modul

Module sind atomare Code-Einheiten, die zur Nutzung in mehreren Dateien wiederverwendet werden können. Module können im Laufe der Zeit verändert werden, ohne dabei Abhängigkeiten in den Dateien, in denen sie bereits benutzt werden, zu zerstören. Du kannst längere oder repetitive Code-Einheiten, wie z. B. Inhaltsdefinitionen, in eine andere Datei auslagern und sie dann mit der Anweisung using importieren.

Das Modul EntitlementInfo sammelt die Namen, Beschreibungen und Kurzbeschreibungen aller Inhalte in der Vorlage. Füge dieses Modul in jede Datei ein, in der du Inhalte definieren musst. Dadurch ist es unnötig, den Namen und andere Variablen für dasselbe Produkt wiederholt neu zu definieren, was Änderungen an den Inhaltsdaten einfacher macht und die Komplexität des Inhalt-Debuggings reduziert.

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

Inhalte definieren

Jede Verse-Berechtigung hat die folgenden Eigenschaften:

• Name: Der Name des Inhalts kann aus bis zu 50 Zeichen bestehen.

• Description: Die lange Beschreibung, die mit dem Inhalt angezeigt wird und bis zu 500 Zeichen umfasst.

• ShortDescription: Eine kurze Beschreibung, die den Inhalt mit bis zu 100 Zeichen zusammenfasst.

• Icon: Ein Bild des Inhalts.

Eine Verse-Berechtigung kann außerdem die folgenden optionalen Eigenschaften haben:

• MaxCount: Die maximale Anzahl dieses Inhalts, die der Spieler zu einem beliebigen Zeitpunkt besitzen kann.

• Consumable: Ist hier True festgelegt, kann der Inhalt mit ConsumeEntitlement verbraucht werden, was die Gesamtanzahl des verbrauchten Inhalts, über die der Nutzer in Epics Systemen verfügt, verringert. Wenn False festgelegt ist, ist der Inhalt ein dauerhafter Gegenstand und wird bei Nutzung nicht verbraucht.

• PaidArea: Ist hier True festgelegt, bietet der Inhalt Zugang zu einem Bereich hinter einer Bezahlschranke.

• PaidRandomItem: Ist hier True festgelegt, werden diese Inhalte gekauft oder über Inhalte eingelöst, um eine zufällige Belohnung zu erhalten.

• ConsequentialToGameplay: Wenn dies auf True gesetzt ist, gewährt der Gegenstand einen bedeutenden Vorteil auf deiner Insel. Siehe Auswirkungen auf das Gameplay für weitere Details.

Im folgenden Snippet verwendest du das zuvor definierte Modul EntitlementInfo, um die Definitionen für deine Inhalte zu erstellen. Um einen Verbrauchsgegenstand-Inhalt zu definieren, muss Consumable auf True gesetzt werden.

Bevor du deine Inhalte definierst, musst du eine Inhalt-Basisklasse erstellen, die für die Inhalte in deinem Erlebnis verwendet wird  – in diesem Fall feature_example_entitlement.

Du musst für jede Inhaltsdefinition auch einen Dateipfad zu einer Symboltextur angeben, da sonst die Validierung deiner Inhaltsdefinition fehlschlägt.

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

Inhaltsangebote

Ein Angebot legt einen Preis in V-Bucks für einen Gegenstand oder ein Asset fest. Jedes Angebot hat seinen eigenen Namen, seine eigene Beschreibung und sein eigenes Symbol, unabhängig von den Berechtigungsspezifikationen. Angebote werden in Verse definiert.

Um den Inhalt zu verkaufen, benötigst du dafür ein entsprechendes Angebot.

Jedes Angebot hat die folgenden Eigenschaften:

• Name: Der Name des Angebots.

• Description: Die lange Beschreibung, die zusammen mit dem Angebot angezeigt wird.

• ShortDescription: Eine kurze Beschreibung, mit der du das Angebot in einem kleineren Dialogfeld zusammenfassen kannst.

• Icon: Ein Bild des Angebots.

• EntitlementType: Eine Erklärung des Inhalts, der im Angebot enthalten ist.

• Price: Ein Preis in V-Bucks. Der Preis darf niemals niedriger als 50 und niemals größer als 5.000 V-Bucks sein. Der Preis muss ein Mehrfaches von 50 sein.

Dieses Snippet demonstriert, wie du Inhaltsangebote definierst und dein vorhandenes EntitlementInfo-Modul für grundlegende Informationen deines Inhaltsangebots verwendest. Du musst zudem ein Symbol, den EntitlementType,  der festlegt, für welchen Inhalt das Angebot gilt, und den Preis in V-Bucks definieren. Du kannst für ein Angebot auch ein optionales Kaufmindestalter definieren, das von einem festen Wert oder einem Ländercode abhängt, oder den Zugriff auf das Angebot je nach Plattformfamilie beschränken. Es ist auch möglich, diese Faktoren zu kombinieren. Einige Beispiele dafür werden im folgenden Snippet demonstriert.

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

Weitere Informationen findest du hier unter Einschränkungen bei Käufen auf Inseln.

 Paketangebote

Pakete werden in Verse definiert und können aus verschiedenen Angeboten, aus einem Stapel eines einzelnen Angebots oder aus einer Kombination aus beidem bestehen. Wie die einfachen Angebote haben auch die Paketangebote einen eigenen Preis, einen eigenen Namen, eine eigene Beschreibung und ein Symbol, das sich von den Inhalten und Angeboten unterscheidet. Du kannst Angebote auch verschachteln, indem du Pakete in ein Paketangebot einbindest. Ein Beispiel wäre ein zeitlich begrenztes Paket, das aus einer Schaufel und einem Paket aus Maissamen-Paketen besteht. Dies ermöglicht es dir, kleinere Pakete als Bausteine für größere, kombinierte Pakete zu verwenden.

Die Standard-Paketarten sind die Folgenden:

• Stapelpaket: Ein Paket, das mehrere Angebote desselben Inhalts enthält und üblicherweise zu einem rabattierten Preis angeboten wird.

• Multi-Angebotspaket: Ein Paket, das Angebote für mehrere Inhalte kombiniert. Dies kann auch eine Mischung aus Stapelangeboten und regulären Angeboten enthalten.

Ein Paket beinhaltet ein Tupel-Array mit Angeboten. Dieses Array beinhaltet das definierte Angebot und eine Int, die die Anzahl der Angebote angibt.

Das folgende Snippet demonstriert den Aufbau eines Trankpakets. Die Angebotsinformationen sind innerhalb des EntitlementInfo-Moduls definiert und beinhalten die PotionCount-Variable. 

ExampleOffers<public> := module:

    using {EntitlementInfo}

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

    potion_pack<public> := class(bundle_offer) :

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

Kaufeinschränkungen

Du kannst den Kauf von Inhalten einschränken, um begrenzt verfügbare Feiertagsgegenstände sowie Aktions- oder Saisonangebote zu erstellen. Zudem kannst du so auch Angebote für bestimmte Regionen erstellen.

GetMinPurchaseAge

Du kannst mit GetMinPurchaseAge eine benutzerdefinierte Kaufbeschränkung für ein bestimmtes entitlement_offer definieren. Dies wird automatisch im Rahmen der Kaufvalidierung aufgerufen und muss deshalb nur vorher definiert werden. Du kannst einen bestimmten ganzzahligen Wert, einen Ländercode oder eine Plattformfamilie festlegen.

Es folgen einige Beispiele für die Funktion 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

Validierung von Spielerinhalten

Die Validierung der Spielerinhalte ist ein notwendiger Schritt, um sicherzustellen, dass die von Spielern gekauften Inhalte zwischen den Sitzungen fortbestehen. Wenn die Inhalte nicht ordnungsgemäß validiert werden, kann es zu Problemen wie z. B. der Duplizierung von Inhalten oder dem Verlust von Inhalten kommen.

Validierung vorheriger Käufe

Das folgende Snippet zeigt eine einfache Inhaltsvalidierung, die durchgeführt wird, wenn ein Spieler einer Sitzung beitritt. Zuerst wird geprüft, ob das Event OnPurchasesChanged dem eingehenden Spieler zugewiesen ist. Falls dies nicht bereits der Fall ist, wird es dem eingehenden Spieler als Nächstes zugewiesen. Als Letztes wird mit ValidatePreviousPurchases ein Datensatz aller gekauften Inhalte für diesen Spieler abgerufen.

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

Käufe abwickeln

Für die Abwicklung von Inhaltskäufen sind vor allem die zwei Funktionen BuyOffer und OnPurchasesChanged wichtig. Die erste Funktion verarbeitet die Logik, die dem Spieler ein Angebot präsentiert und den Kauf validiert. Die zweite Funktion verarbeitet die Logik für eine erfolgreiche Transaktion oder Rückerstattung. Diese beiden Funktionen werden in den folgenden Snippets demonstriert. 

# 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

Verbrauchsgegenstände handhaben

Um einen Verbrauchsgegenstand-Inhalt zu verbrauchen, musst du die Funktion ConsumeEntitlement aus der Marketplace-Verse-API verwenden. Sobald der Gegenstand erfolgreich verbraucht wurde, muss die Logik für den nach dem Verbrauch generierten Effekt verarbeitet werden. Die Count der Inhalte, die der Spieler besitzt, wird um die in der Funktion verbrauchte Count verringert.

Das folgende Snippet zeigt, wie ein bestimmter Inhalt von einem bestimmten Spieler verbraucht wird.

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

Inhalte gewähren

Im Gegensatz zum Kauf eines Inhalts, für den V-Bucks erforderlich sind, kannst du den Spielern Inhalte zudem mit der GrantEntitlement-Methode gewähren.

Zu den möglichen Anwendungsfällen für das Gewähren von Inhalten gehören Gegenstände von Werbeaktionen, kostenlose Verbrauchsgegenstände zum Ausprobieren und das Wiederherstellen verlorener Gegenstände aufgrund von Bugs oder Glitches.

Dieses Snippet demonstriert eine Methode, die deinen Spielern Inhalte gewährt.

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

Deine Inhaltsangebote den Spielern zeigen

Das Marketplace module bietet mit der Funktion ShowOffersDialog eine integrierte Shop-Benutzeroberfläche zur Verwendung auf deinen Inseln. Das folgende Snippet demonstriert eine Methode zum Anzeigen eines Shops mit Angeboten für einen bestimmten Spieler.

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

Vollständiger Code

using { /Fortnite.com/Devices }

using { /Fortnite.com/Marketplace }

using { /UnrealEngine.com/Temporary/Diagnostics }

using { /Verse.org/Assets }

using { /Verse.org/Simulation }