Szablon urządzenia transakcji na wyspie

Urządzenie transakcji na wyspie Verse zawiera szablon transakcji na wyspie. Zawiera ono wszystkie implementacje kluczowych aspektów modułu rynku w interfejsie API Verse. Znajdują się w nim przedmioty, oferty, oferty zestawów oraz procedura zakupu z wykorzystaniem domyślnego UI witryny sklepu. Korzystaj z tego kodu jako przewodnika, aby szybciej skonfigurować witrynę sklepu.

Aby uzyskać dostęp do tego urządzenia:

• Przejdź do Eksploratora Verse.

• Kliknij prawym przyciskiem myszy nazwę projektu.

• Wybierz opcję Dodaj nowy plik Verse do projektu.

• Wybierz pozycję Urządzenie transakcji na wyspie.

Tworzenie przedmiotów

Przedmioty w języku Verse definiuje się jako uprawnienia, które kwalifikują się do jednej z dwóch kategorii: przedmioty jednorazowe, które znikają z ekwipunku gracza po wykorzystaniu, oraz przedmioty trwałe, które gracz może zachować, gdyż nie są one usuwane z jego ekwipunku.

Moduł EntitlementInfo

Moduły to niepodzielne jednostki kodu, które można wielokrotnie wykorzystywać w wielu plikach. Moduły można z czasem modyfikować bez przerywania zależności w pliku, w którym dany moduł jest już używany. Pozwalają one oddzielić długie i powtarzalne jednostki kodu, takie jak definicje uprawnień, do innego pliku, a następnie zaimportować je za pomocą polecenia using.

Moduł EntitlementInfo gromadzi nazwy, opisy i krótkie opisy wszystkich uprawnień w szablonie. Dołącz ten moduł do każdego pliku, w którym chcesz zdefiniować uprawnienia, bez konieczności wielokrotnego definiowania nazwy i innych zmiennych dla tego samego produktu. Upraszcza to wprowadzanie zmian w informacjach o uprawnieniach i zmniejsza złożoność debugowania uprawnień.

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

Definiowanie uprawnień

Każde uprawnienie Verse ma następujące właściwości:

• Name: Nazwa uprawnienia składająca się z maksymalnie 50 znaków

• Description: Długi opis, który jest wyświetlany wraz z uprawnieniem, składający się z maksymalnie 500 znaków.

• ShortDescription: Krótki opis podsumowujący uprawnienie, maksymalnie 100 znaków.

• Icon: Obrazek przedstawiający uprawnienie.

Uprawnienie Verse może mieć również następujące właściwości opcjonalne:

• MaxCount: Maksymalna liczba sztuk danego uprawnienia, jaką gracz może posiadać w dowolnej chwili.

• Consumable: Jeśli ustawiono na wartość true, uprawnienie może zostać zużyte za pomocą ConsumeEntitlement , co zmniejsza łączną liczbę zużytych uprawnień użytkownika w systemach Epic. Jeśli jest to ustawione na wartość false, uprawnienie będzie przedmiotem trwałym, a jego użycie nie będzie powodowało usunięcia go z ekwipunku.

• PaidArea: W przypadku ustawienia dla tej opcji wartości true, dane uprawnienie zapewnia dostęp do obszaru ukrytego za zaporą płatniczą.

• PaidRandomItem: W przypadku ustawienia dla tej opcji wartości true, uprawnienia te są kupowane lub odbierane za zawartość w celu uzyskania losowej nagrody.

• ConsequentialToGameplay: Jeśli jest to ustawione na wartość true, przedmiot zapewnia graczowi znaczącą przewagę na twojej wyspie. Aby uzyskać więcej szczegółów, patrz: Wpływające na rozgrywkę.

W poniższym fragmencie kodu wykorzystasz zdefiniowany wcześniej moduł EntitlementInfo do zbudowania definicji swoich uprawnień. Aby zdefiniować uprawnienie jednorazowe, opcja Consumable musi być ustawiona na wartość true.

Przed zdefiniowaniem uprawnień musisz utworzyć klasę uprawnień bazowych, która będzie używana w uprawnieniach w twojej przygodzie  – w tym przypadku, feature_example_entitlement.

Należy również zdefiniować ścieżkę pliku do tekstury ikony dla każdej definicji uprawnienia, w przeciwnym razie definicja uprawnienia nie zaliczy pomyślnie walidacji.

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

Oferty uprawnień

Oferta określa cenę przedmiotu lub zasobu w V-dolcach. Każda oferta ma własną nazwę, opis oraz ikonę, niezależnie od specyfikacji uprawnienia. Ofertę definiuje się w Verse.

Aby sprzedać uprawnienie, musisz mieć odpowiadającą mu ofertę na to uprawnienie.

Każda oferta ma następujące właściwości:

• Name: Nazwa oferty.

• Description: Długi opis wyświetlany wraz z ofertą.

• ShortDescription: Krótki opis służący do podsumowania oferty w mniejszych oknach dialogowych.

• Icon: Obrazek przedstawiający ofertę.

• EntitlementType: Deklaracja uprawnienia uwzględnionego w ofercie.

• Cena: Cena w V-dolcach. Cena nie może być mniejsza niż 50 V-dolców ani większa niż 5000 V-dolców. Musi być ona wielokrotnością liczby 50.

Ten fragment demonstruje, jak definiować oferty uprawnień, wykorzystując istniejący moduł EntitlementInfo do podstawowych informacji o ofertach uprawnień. Musisz również zdefiniować ikonę, EntitlementType —  który określa uprawnienie, którego dotyczy oferta, oraz cenę w V-dolcach. Możesz też zdefiniować opcjonalny minimalny wiek użytkownika dla oferty, w zależności od stałej wartości, kodu kraju, albo ograniczyć dostęp do oferty według rodziny platform, czy też kombinacji tych kryteriów. Kilka przykładów pokazano w poniższym fragmencie.

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

Aby dowiedzieć się więcej, patrz: Ograniczenia dotyczące transakcji na wyspie.

 Oferty zestawów

Zestawy definiuje się w Verse. Mogą one zawierać kombinację różnych ofert, stosy tej samej oferty lub połączenie obu tych wariantów. Podobnie jak w przypadku prostych ofert, oferty zestawów mają określoną własną cenę, nazwę oraz opis, a także ikonę, która odróżnia je od uprawnień i ofert. Możesz również zagnieździć oferty, dodając zestawy do oferty zestawów. Przykładem będzie ograniczony czasowo zestaw zawierający łopatę oraz zestaw pakietów nasion kukurydzy. W ten sposób można wykorzystać mniejsze zestawy jako bloki konstrukcyjne do tworzenia większych zestawów łączonych.

Standardowymi typami zestawów są:

• Zestaw ze stosami przedmiotów: Zestaw zawierający wiele ofert tego samego uprawnienia, zazwyczaj po niższej cenie.

• Zestaw z wieloma ofertami: Zestaw łączący oferty wielu uprawnień. Może zawierać również połączenie ofert stosów przedmiotów i zwykłych ofert.

Zestaw zawiera tablicę krotek ofert, która zawiera zdefiniowaną ofertę oraz wartość int wskazującą liczbę ofert.

Poniższy fragment przedstawia konstrukcję zestawu mikstur. Informacje o ofercie są definiowane w module EntitlementInfo, w tym zmienna PotionCount. 

ExampleOffers<public> := module:

    using {EntitlementInfo}

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

    potion_pack<public> := class(bundle_offer) :

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

Ograniczenia zakupu

Możesz ograniczyć zakupy uprawnień, aby umożliwić tworzenie limitowanych przedmiotów świątecznych, ofert promocyjnych lub sezonowych oraz tworzenie treści specyficznych dla regionu.

GetMinPurchaseAge

Za pomocą GetMinPurchaseAge zdefiniujesz niestandardowe ograniczenie zakupów dla określonej entitlement_offer. Jest to automatycznie wywoływane jako część weryfikacji zakupu, dlatego wymaga jedynie definicji. Możesz zdefiniować konkretną wartość całkowitą, kod kraju lub rodzinę platform.

Poniżej znajdują się przykłady funkcji 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

Weryfikacja uprawnień gracza

Weryfikacja uprawnień gracza to krok niezbędny, aby zapewnić zachowanie uprawnień zakupionych przez graczy między sesjami. Brak prawidłowej walidacji uprawnień może skutkować takimi problemami, jak duplikowanie uprawnień lub ich utrata.

Weryfikacja poprzednich zakupów

Poniższy fragment kodu przedstawia prostą weryfikację uprawnień wykonywaną, gdy gracz dołącza do sesji. Najpierw sprawdza, czy przychodzący gracz jest zasubskrybowany dla zdarzenia OnPurchasesChanged. Następnie przychodzący gracz zostanie subskrybowany, jeśli jeszcze nie jest subskrybowany. Na końcu pobierany jest rekord wszystkich zakupionych uprawnień dla tego gracza za pomocą 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

Obsługa zakupów

Dwie główne funkcje wykorzystywane do obsługi zakupów uprawnień to BuyOffer i OnPurchasesChanged. Pierwsza funkcja obsługuje logikę przedstawienia graczowi oferty i zatwierdzenia zakupu. Druga funkcja obsługuje logikę pomyślnej transakcji lub zwrotu. Poniższe fragmenty ilustrują te dwie funkcje. 

# 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

Obsługa przedmiotów jednorazowych

Aby skorzystać z uprawnienia jednorazowego, należy użyć funkcji ConsumeEntitlement z interfejsu API rynku Verse. Gdy konsumpcja zakończy się powodzeniem, musisz obsłużyć logikę efektu generowanego po zużyciu. Count (liczba) uprawnień, które posiada gracz, będzie pomniejszona o Count (liczbę) zużytą w funkcji.

Poniższy fragment kodu pokazuje, jak konkretne uprawnienie zostaje wykorzystane przez określonego gracza.

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

Przyznawanie uprawnień

W przeciwieństwie do zakupu uprawnienia, które wymaga V-dolców, uprawnienia można również przyznawać graczom za pomocą metody GrantEntitlement.

Potencjalne przypadki użycia przyznania uprawnienia obejmują przedmioty promocyjne, bezpłatne próbki przedmiotów jednorazowych oraz przywracanie przedmiotów utraconych w wyniku błędów lub usterek.

Ten fragment przedstawia metodę przyznawania uprawnień graczom.

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

Pokaż graczom swoje oferty uprawnień

Marketplace module zapewnia wbudowany interfejs witryny sklepowej do użytku na wyspach za pomocą funkcji ShowOffersDialog. Poniższy fragment kodu demonstruje metodę wyświetlania witryny sklepowej, która pokazuje oferty dla konkretnego gracza.

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

Gotowy kod

using { /Fortnite.com/Devices }

using { /Fortnite.com/Marketplace }

using { /UnrealEngine.com/Temporary/Diagnostics }

using { /Verse.org/Assets }

using { /Verse.org/Simulation }