com.hashbang.monarch.beamable.content v1.0.6

Monarch Beamable Content

The Beamable Content Package is a Unity package that provides a framework for loading and working with content in the Beamable game engine. It allows developers to easily manage game content such as items, achievements, and game types, as well as track player statistics and inventory.

The package includes a ContentService class that handles the loading and caching of Beamable content, as well as several other services that help manage specific types of content such as CurrencyService for managing in-game currencies, AnnouncementService for managing in-game announcements, InventoryService for managing player inventories, and StatsService for tracking player statistics.

Developers can also extend the package by implementing the IContentResolver interface to create custom content resolvers that can be used to load and cache content from external sources.

The Beamable Content Package is designed to work seamlessly with the rest of the Beamable game engine, allowing developers to quickly and easily integrate content into their games without having to worry about the underlying implementation details.

Adding the Loader to StartupApp

To use the Monarch Beamable Content loader, you need to add it to the list of loaders in your StartupApp.

_loader.RegisterLoader(new ContentLoader());

Using ContentResolvers

To load Beamable Content, you need to use a ContentResolver. A ContentResolver is responsible for resolving Beamable Content based on a given query. You can create your own ContentResolver by implementing the IContentResolver interface. ContentResolver's also allow you to customize how and when content is loaded. If you have specific conditions that you only want to load specific content at start, then you can put additional logic in the content loader to account for this.

Example use case: I only want to load Weapons available when a player reaches level 5.

Here is an example of using a ContentResolver to load Beamable Content of type 'GameItem':

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Beamable.Common.Content;

public class GameItemContentResolver : IContentResolver
{
    // The type of content item that this resolver handles
    public string ItemType => "items.GameItem";

    // Resolve the content items of this type
    public async Task<IList<IContentObject>> ResolveContent(ClientManifest manifest)
    {
        // Filter the manifest to only include the GameItem type
        ClientManifest filteredManifest = manifest.Filter(new ContentQuery()
        {
            TypeConstraints = new HashSet<Type> { typeof(GameItem) }
        });

        // Resolve the filtered manifest to get the GameItem content items
        IList<IContentObject> resolvedContent = await filteredManifest.ResolveAll();

        return resolvedContent;
    }
}

In this example, the GameItemContentResolver class implements the IContentResolver interface. It defines the ItemType property, which is a string that identifies the type of content that the resolver handles. In this case, the ItemType is "items.GameItem", indicating that this resolver handles content items of type GameItem.

Note: You can resolve items that are items in the content manager that extend from ItemContent, you may also use them to resolve custom types that extend ContentObject.

Getting Content from the Cache

Once the ContentService has finished loading content, it can be accessed from the cache using the GetContent method. This method takes two parameters: the collection name and the ID of the content object.

Here's an example of using the GetContent method to retrieve a GameItem object:

private async void Start()
{
    if (!MonarchApp.IsInitialized || StartupApp.Instance == null) return;
    await StartupApp.Instance.WaitForReady();
    
    var contentService = IoC.inject.Get<ContentService>();
    var gameItem = await contentService.GetContent("items", "GameItem");
}

In the example above, we first check if MonarchApp is initialized and if StartupApp.Instance is available. If so, we wait for the app to become ready.

Then, we retrieve the ContentService instance using the dependency injection container, and use the GetContent method to retrieve a GameItem object from the "items" collection.

The GetContent method returns a Task that resolves to an IContentObject. In this case, since we know we're retrieving a GameItem object, we can cast the result to a GameItem.

Announcments

The Announcement Service is a Monarch service that provides access to the Beamable Announcement API. It enables developers to receive and display announcements to their players in real-time.

To use the Announcement Service, you must first initialize it by creating an instance of it using an injector in your application. Once you have the instance, you can use its methods to retrieve and display announcements.

To get announcements, you can use the GetAnnouncements method. This method returns a list of AnnouncementView objects that contain the announcement's title, message, and other metadata. Here's an example of how to use the method:

AnnouncementService announcementService = IoC.inject.Get<AnnouncementService>();
await announcementService.GetAnnouncements();

foreach (var announcement in announcementService.Announcements)
{
    Debug.Log($"Title: {announcement.title}");
    Debug.Log($"Message: {announcement.message}");
    // ... Display other announcement properties as needed
}

To receive new announcements as they arrive, you can subscribe to the OnAnnouncementsReceived event. This event fires whenever a new announcement is added to the announcement queue. Here's an example of how to subscribe to the event:

AnnouncementService announcementService = IoC.inject.Get<AnnouncementService>();
await announcementService.Subscribe();

announcementService.OnAnnouncementsReceived.AddListener(OnNewAnnouncementsReceived);

void OnNewAnnouncementsReceived(List<AnnouncementView> announcements)
{
    Debug.Log($"New announcement received: {announcements[0].title}");
}

Note that the OnAnnouncementsReceived event fires on the main thread, so it's safe to update the UI from within the event handler.

Once you have retrieved an announcement, you can mark it as read or deleted using the MarkAsRead and MarkAsDeleted methods, respectively. Here's an example of how to mark an announcement as read:

AnnouncementService announcementService = IoC.inject.Get<AnnouncementService>();
await announcementService.MarkAsRead(announcement.id);

Overall, the Announcement Service provides a convenient way to manage announcements in your game and keep your players informed about updates and events.

Currency Service

The Currency Service is a Monarch service responsible for handling currency-related operations for a Beamable game. It allows the game to monitor and update the player's currency amounts at runtime.

To use the Currency Service, first, get an instance of the service through the IoC Injector. Then, call the Subscribe method to start listening for changes to the player's currencies. Once subscribed, the OnCurrencyContentChanged event will be triggered whenever a currency is added, removed, or updated.

The CurrencyUpdated event is provided to make it easy to listen for updates to a specific currency. This event takes two parameters: a string representing the currency type and a long representing the new currency amount.

// Get an instance of the Currency Service
var currencyService = IoC.inject.Get<CurrencyService>();

// Subscribe to the Currency Service
await currencyService.Subscribe();

// Listen for changes to a specific currency
currencyService.CurrencyUpdated.AddListener((currency, amount) =>
{
    Debug.Log($"Currency {currency} changed to {amount}");
});

// Get the current amount of a currency
var coins = currencyService.GetCurrency("coins");

Note that the Currency Service will not receive currency updates until the inventory has been loaded. Therefore, it is necessary to wait for the content to be received by calling the WaitForContentReceived method.

    await _currencyService.Subscribe();
    await _currencyService.WaitForContentReceived();

Inventory Service

The InventoryService is a class in the Monarch game framework that provides functionality for managing player inventories in a Beamable game. It provides methods for getting and refreshing a player's inventory, subscribing to inventory update events, and accessing the current state of the player's inventory. The service is built on top of the Beamable SDK's inventory API and simplifies the process of managing player inventory data in a game.

    if (!MonarchApp.IsInitialized || StartupApp.Instance == null) return;
    await StartupApp.Instance.WaitForReady();
    
    _inventoryService = IoC.inject.Get<inventoryService>();

Getting Inventory

To fetch the player's inventory, call the GetInventory() method:

await _inventoryService.GetInventory();

Note that you must call this method before subscribing to any inventory updates.

To retrieve the current inventory items, call the GetItems() method:

var items = _inventoryService.GetItems();