Tutorial: LiveOps Features

Overview

In the previous Tutorial: Minimal SDK Integration chapter, we integrated the Metaplay SDK into our sample project, making it ready for adopting Metaplay's advanced features.

In this chapter, we will integrate some of Metaplay's LiveOps features into our project. Specifically, we will add over-the-air updatable game configs, player segmentation, A/B testing, and the LiveOps events feature for dynamic game content.

We can implement each feature as its own step:

Start Using Game Configs
Implement Segmentation
Create Experiments
Implement LiveOps Events

SDK Features Quick Reference

To keep the tutorial focused, we will not dive deep into the SDK features themselves. Here are the concepts we'll be applying in this chapter, along with links for further reading if you're curious:

Working with Game Configs - We will adopt the game configs feature to make the game data over-the-air updatable.
Implementing Player Segments - We will use the player segments feature to group players based on different criteria.
Introduction to Experiments - We will design and implement experiments (A/B tests) targeted at player segments.
Implementing LiveOps Events - We will use the LiveOps events feature to create, schedule, and manage in-game events.
Working with Generated Dashboard UI - We will use the generated dashboard UI to configure a liveops event in the dashboard.

Start Using Game Configs

Game configs are the center of a lot of Metaplay features, but most importantly they enable over-the-air updating and A/B testing your configuration.

Preparation

We have created a Google Sheets spreadsheet to use as the source data for our game configs. You could use any other data source instead, but Google Sheets remains popular for game designers and is a good starting point.

We kept the data as simple as possible to get started, and will be incrementally adding more content to the game config sheet in upcoming steps. For convenience, we will be creating full copies of the sheet for each step of this tutorial to make it easier to follow along.

Implement Game Configs

To get started, we'll move over the configuration for how often power ups and premium currency spawns during a level. Here is an excerpt of our source spreadsheet:

Member	Value	// Comment
EvaluationInterval	1.5	The distance in meters between each possible item location
MinPowerUpInterval	100	The minimum distance in meters since the last power up, starting at 0% chance up to 100% at MaxPowerUpInterval
MaxPowerUpInterval	5000
MinPremiumInterval	1000	The minimum distance in meters since the last premium currency, starting at 0% chance up to 100% at MaxPremiumInterval
MaxPremiumInterval	10000

Let's start by defining the data format of our configuration. Define a new class inheriting from GameConfigKeyValue<TSelf>:

Assets/SharedCode/GameConfigs/TrackConfig.cs

[MetaSerializable]
public class TrackConfig : GameConfigKeyValue<TrackConfig>
{
    [MetaMember(1)]
    public F32 EvaluationInterval { get; private set; }
    [MetaMember(2)]
    public int MinPowerUpInterval { get; private set; }
    [MetaMember(3)]
    public int MaxPowerUpInterval { get; private set; }
    [MetaMember(4)]
    public int MinPremiumInterval { get; private set; }
    [MetaMember(5)]
    public int MaxPremiumInterval { get; private set; }
}

After that, create a new file SharedGameConfig.cs in the SharedCode directory, and define a new class inheriting from SharedGameConfigBase with an entry TrackConfig:

Assets/SharedCode/GameConfigs/SharedGameConfig.cs

public class SharedGameConfig : SharedGameConfigBase
{
    [GameConfigEntry("TrackConfig")] 
    public TrackConfig TrackConfig { get; private set; } 
}

And, that's all! We can now use TrackConfig anywhere in our code:

Assets/Scripts/Tracks/TrackManager.cs

TrackConfig config = MetaplayClient.PlayerModel?.GameConfig.TrackConfig;

// The distance between each powerup and currency
float increment = config.EvaluationInterval.Float;

Let's do something similar for the shop. A shop is a collection of items, so let's use a GameConfigLibrary instead. Define the data format for each item in the shop by inheriting from IGameConfigData<TKey>:

Assets/SharedCode/GameConfigs/ShopItem.cs

[MetaSerializable]
public class ShopId : StringId<ShopId> {}

[MetaSerializable]
public class ShopItem : IGameConfigData<ShopId>
{
    [MetaMember(1)]
    public ShopId ConfigKey { get; private set; }

    [MetaMember(2)]
    public Category Category { get; private set; }

    [MetaMember(3)]
    public PlayerReward Reward { get; private set; }

    [MetaMember(4)]
    public int PremiumCost { get; private set; }

    [MetaMember(5)]
    public int CoinCost { get; private set; }
}

MetaRewards

We're using MetaRewards to define the rewards that are given to the player when they purchase an item. MetaRewards are a Metaplay feature to streamline giving items and other rewards to players, and you can find more about them on the Implementing MetaRewards page.

As you might've noticed, the shop item contains a new ConfigKey property. We're working with a dictionary of items, which means that each item needs a unique key. This is what an excerpt of our source spreadsheet looks like:

ConfigKey #key	Category	Reward	PremiumCost	CoinCost
Magnet	Consumable	Magnet	0	750
Life	Consumable	Life	5	2000
Raccoon	Character	"Rubbish Raccoon"	20	50000
TrashCat	Character	"Trash Cat"	0	0
Raccoon_Safety	Accessory	"Rubbish Raccoon"/Safety	10	20000

Let's continue. Add a new GameConfigLibrary to the SharedGameConfig:

Assets/SharedCode/GameConfigs/SharedGameConfig.cs

public class SharedGameConfig : SharedGameConfigBase
{
    [GameConfigEntry("TrackConfig")]
    public TrackConfig TrackConfig { get; private set; }

    [GameConfigEntry("Shop")] 
    public GameConfigLibrary<ShopId, ShopItem> Shop { get; private set; } 
}

And update the shop to read from the game config instead of a static configuration:

Assets/Scripts/UI/Shop/ShopItemList.cs

public override void Populate()
{
    m_RefreshCallback = null;
    foreach (Transform t in listRoot)
    {
        Destroy(t.gameObject);
    }

    // foreach (var (key, value) in Shop.Instance.Consumables)
    foreach (var (key, value) in MetaplayClient.PlayerModel.GameConfig.Shop.Where(x => x.Value.Category == Category.Consumable)) 
    {
        SpawnShopItem(value, key);
    }
}

Lastly, we'll create and use a BuyItem action to authoritatively add the item to the user's inventory and subtract the currency:

Assets/SharedCode/Player/PlayerActions.cs

[ModelAction(ActionCodes.BuyItem)]
public class BuyItemAction : PlayerAction
{
    public ShopId ID { get; }

    [MetaDeserializationConstructor]
    public BuyItemAction(ShopId id)
    {
        ID = id;
    }

    public override MetaActionResult Execute(PlayerModel player, bool commit)
    {
        // Verify that the item the player is trying to purchase does actually exist
        if (!player.GameConfig.Shop.TryGetValue(ID, out var shopItem))
            return ActionResult.InvalidItem;

        int newCoins = player.PlayerData.NumCoins - shopItem.CoinCost;
        int newPremium = player.PlayerData.NumPremium - shopItem.PremiumCost;

        // Verify that the player can afford the item
        if (newCoins < 0 || newPremium < 0)
            return ActionResult.InsufficientFunds;

        if (commit)
        {
            // Purchase success! Subtract the funds and give the reward to the user
            player.PlayerData.NumCoins = newCoins;
            player.PlayerData.NumPremium = newPremium;

            shopItem.Reward.InvokeConsume(player, source: null);

            player.EventStream.Event(new ItemReceivedEvent(shopItem.Reward.Type, shopItem.Category.ToString(), 1, shopItem.CoinCost, shopItem.PremiumCost, Context.Store));
        }

        return MetaActionResult.Success;
    }
}

Assets/Scripts/UI/Shop/ShopItemList.cs

private static bool ExecuteBuyItem(ShopId id)
{
    BuyItemAction action = new BuyItemAction(id);
    return MetaplayClient.PlayerContext.ExecuteAction(action).IsSuccess;
}

That's it!

We introduced game configs to configure power up spawning, populate the shop as well as an action to purchase items in a cheat-proof way. All that is left is to create and build your game configs.

Build & Publish in Unity Editor

The simplest way to build and publish game configs is to use Metaplay's Game Config Build Window in Unity.

In Unity, open the Game Config Build Window from the Metaplay > Game Config Build Window menu item. Game configs can be built from one or more different build sources. We've already set up the development sheet as a source for you.
Press Build. You'll be asked to login to your Google account to authorize reading the game config sheet.
If your server is already running, select the desired environment from the dropdown and press Publish. If your server is not running, start it with metaplay dev server and it will detect that your game config files have changed and automatically publish it.
After publishing, open the Game Configs page of the LiveOps Dashboard to see your newly created game config as the active config. Press View config to find more info about the config.

Building & Publishing via LiveOps Dashboard

You can also configure the game server to be able to build and publish game configs, so that you can do builds without touching Unity. For simplicity, we'll be using the Unity editor for this tutorial. Check out Managing Game Configs from the Dashboard for more info.

Optional: Modify the Game Config

If you want to play around with the game config, you can modify the values in the game config sheet and build it again.

Create a copy of our example game config spread sheet.
Using the Share modal, allow "Anyone with the link" to view the spreadsheet.
Modify the values that you want to change. You could, for example, change the prices of the consumables in the Shop sheet.
Open the Game Config Build Window in Unity.
Change the Default Source to Custom GoogleSheetBuildSource. Fill in a name and the spreadsheet url.
Press Build Config.
Start the game and your shop will be updated to reflect the new prices.

Implement Segmentation

Now that we have a way to configure the game, we can move on to implementing player segmentation.

Segments in Metaplay are built from a set of PlayerPropertys. At it's simplest, a PlayerProperty is a scriptable way to fetch data about your player. The SDK combines sets of player properties to compare and evaluate against the player model. Segments can then be used in a variety of SDK features, from A/B testing to push notifications, but you can also use segments in your own features.

The end goal is to have segments be configurable via game configs, so that no code changes or server builds are needed to add new segments.

Implement Player Properties

Before we get started creating segments, we have to create a new section in the game configs. Add a new library to the SharedGameConfig:

Assets/SharedCode/GameConfigs/SharedGameConfig.cs

public class SharedGameConfig : SharedGameConfigBase
{
    [GameConfigEntry("TrackConfig")]
    public TrackConfig TrackConfig { get; private set; }

    [GameConfigEntry("Shop")]
    public GameConfigLibrary<ShopId, ShopItem> Shop { get; private set; }

    [GameConfigEntry("PlayerSegments")] 
    [GameConfigEntryTransform(typeof(DefaultPlayerSegmentBasicInfoSourceItem))] 
    public GameConfigLibrary<PlayerSegmentId, DefaultPlayerSegmentInfo> PlayerSegments { get; private set; }      
}

The simplest player property just returns a value and has a display name. The SDK handles all the grunt work of comparisons and further evaluation. Let's create a player property that returns the total amount of soft currency a player currently has:

Assets/SharedCode/Segments/PlayerProperties.cs

[MetaSerializableDerived(4)]
public class SoftCurrencyProperty : TypedPlayerPropertyId<int>
{
    public override string DisplayName => "Soft Currency";
    public override int GetTypedValueForPlayer(IPlayerModelBase player) => ((PlayerModel)player).PlayerData.NumCoins;
}

More complex player properties are possible as well. For example, RunsWithTheme takes a parameter to determine how many runs the player has completed with a specific theme. These work with a bit of custom parsing logic that turns RunsWithHistory/Night into a new instance of RunsWithTheme with Theme set to Night. For more info, check out Defining Player Properties.

Assets/SharedCode/Segments/PlayerProperties.cs

[MetaSerializableDerived(7)]
public class RunsWithThemeProperty : TypedPlayerPropertyId<int>
{
    public override string DisplayName => $"Number of completed runs with theme {Theme}";

    [MetaMember(1)] public string Theme { get; set; }

    public override int GetTypedValueForPlayer(IPlayerModelBase player)
    {
        PlayerModel playerModel = (PlayerModel)player;
        return playerModel.RunHistory.Count(x => x.ThemeUsed == Theme);
    }
}

Add all the player properties you might need at this point. We have added a few more that were appropriate for the Trash Dash project, but these will be very game-specific. You can always add more later!

With player properties defined, we can then create segments in the new PlayerSegments game config library.

PropMin and PropMax

Numeric and time properties (such as Gold or AccountAge) are checked against ranges specified by the PropMin and PropMax columns. For less than or greater than behavior, either PropMin or PropMax can be omitted. Non-numeric properties (such as LastKnownCountry, a string) are not range-compared; instead, the PropMin column is repurposed to contain the required value. The PropMax column is not used for non-numeric Properties.

Optional: Inspecting Segments in Action

You can use the LiveOps Dashboard to see all your defined segments and what segments any given player belongs to. This makes debugging segments a breeze!

In Unity, Use the Game Config Build Window to build the latest game configs.
Restart the local server with metaplay dev server.
Open the players page in the LiveOps Dashboard at http://localhost:5550/players.
Open the details page of your player. It should be the only one on the list.
In the Segments & Targeting tab, you can see which segments your player is currently in.

You can also visit the Player Segments page at http://localhost:5550/segments to see an overview of all configured segments.

Create Experiments

Now that we have over-the-air configuration and segments, we can use the experiments feature of Metaplay's game configs system to add A/B tests to the game.

Add Experiments to Game Configs

This time, we'll need to add a PlayerExperiments library to the ServerGameConfig (instead of SharedGameConfig), to ensure that your experiments are not leaked to all your players.

Create a new file ServerGameConfig.cs in the SharedCode directory, and define a new class inheriting from ServerGameConfigBase with an entry PlayerExperiments:

Assets/SharedCode/GameConfigs/ServerGameConfig.cs

public class ServerGameConfig : ServerGameConfigBase
{
    [GameConfigEntry(PlayerExperimentsEntryName)] 
    public GameConfigLibrary<PlayerExperimentId, PlayerExperimentInfo> PlayerExperiments { get; private set; } 
}

We will configure three experiments in the PlayerExperiments game config library, and assign new values to TrackConfig when a player is enrolled in an experiment. Each experiment will have a control group and two variant groups.

In this example, we've overwritten the power up spawn rates for the PowerUpTuning experiment.

Note how there are no further code changes required in this step as experiments are configured in the existing game configs! The client or server do not need any additional code to support experiments. The Metaplay SDK will handle all the work of fetching the correct experiment configuration and keeping it in sync on both the server and client.

The 3 new experiments in the game config are:

Power Up Tuning - Do less or more power-ups improve session length?
Random Premium Currency Tuning - Does decreasing/increasing the scarcity of premium currency improve monetization?
Cheater Balancing - Found some cheaters in your game but don't want to ban them straight away? Enroll them into this to have a little fun with them.

Experiments are a powerful feature that can get complicated in large games. This is a positive problem of having a successful game with lots to test!

Managing Experiments

We have built a lot of quality-of-life tooling into the LiveOps Dashboard to help manage a large amount of parallel experiments.

In the Unity editor, use the Game Config Build Window to build the game configs with the experiments in them.
Visit the Experiments page at http://localhost:5550/experiments to see an overview of all configured experiments.
- Pick an experiment of your choosing and take a look at the configuration.
- Select a segment to target the experiment to. Depending on how much you played, your player will likely be in the Premium Currency <= 50 segment.
- After that, press Rollout to release your experiment into the wild.
Visit the players page in the LiveOps Dashboard at http://localhost:5550/players.
- Open the details of your player. It should be the only one on the list.
- In the Segments & Targeting tab, you can see which experiments your player is currently in.
- If your player is not yet in the experiment, you can use the Admin Actions > Join Experiment action to force your player into the experiment.

Implement LiveOps Events

To take more advantage of segments and targeting, we will next implement a dynamic in-game event using Metaplay's LiveOps event system. The event will temporarily enable the night theme for players, and give them a chance to permanently unlock the night theme if they play enough times.

Create an Event in Shared Code

LiveOps events usually consist of 2 different components: configuration (LiveOpsEventContent) and the player specific state (LiveOpsEventModel). We'll set this up in a re-usable fashion, the same implementation can be used if we add new themes to the game. The event content will contain the theme we're enabling, how many times the player has to attempt the theme to unlock the theme permanently, and a title to show in the game.

Define a new class inheriting from LiveOpsEventContent:

Assets/SharedCode/Events/ThemeEvent.cs

[LiveOpsEvent(1)]
public class ThemeEvent : LiveOpsEventContent
{
    [MetaMember(1)]
    [MetaFormDisplayProps("Theme", DisplayHint = "Which theme to enable for the users")]
    [MetaFormFieldCustomValidator(typeof(ThemeValidator))]
    public Theme Theme { get; private set; } = Theme.NightTime;

    [MetaMember(2)]
    [MetaFormDisplayProps("Perma Unlock Threshold", DisplayHint = "After how many runs the player will permanently unlock this theme")]
    public int PermaUnlockThreshold = 10;

    [MetaMember(3)]
    [MetaFormDisplayProps("Event In-Game Title", DisplayHint = "Event title in Game UI")]
    public string EventInGameTitle;
}

The configuration will be shown in the dashboard using Metaplay's Generated UI framework, we've used optional attributes MetaFormDisplayProps and MetaFormFieldCustomValidator to make the form more user-friendly.

Next, define the player specific state:

Assets/SharedCode/Events/ThemeEvent.cs

[MetaSerializableDerived(1)]
public partial class ThemeEventModel : PlayerLiveOpsEventModel<ThemeEvent, PlayerModel>
{
    [MetaMember(1)] public int RunsInThemeSinceStart { get; private set; }

    [MetaMember(2)] public bool RewardGiven { get; private set; }

    public void IncrementRunAndReward(PlayerModel player, string themeUsed)
    {
        if (Content.Theme.ToString() == themeUsed)
        {
            RunsInThemeSinceStart++;

            if (RunsInThemeSinceStart >= Content.PermaUnlockThreshold && !RewardGiven)
            {
                RewardGiven = true;
                if (!player.PlayerData.Themes.Contains(themeUsed))
                {
                    player.PlayerData.Themes.Add(themeUsed);
                }
            }
        }
    }
}

That's all you need for the event to show up in the dashboard and be able to enroll players into the event.

Update the In-Game UI

Next, let's update the client to show the event.

Invoke IncrementRunAndReward() from the EndRunAction:

Assets/SharedCode/Player/PlayerActions.cs

foreach (var model in player.LiveOpsEvents.EventModels.Values.OfType<ThemeEventModel>().Where(x=>x.Phase.IsActivePhase()))
{
    model.IncrementRunAndReward(player, ThemeUsed);
}

We'll use a client listener to sync the event becoming active/inactive to the UI.

Add a new method to the client listener interface:

Assets/SharedCode/Player/PlayerModelListeners.cs

public interface IPlayerModelClientListener
{
    void ThemeEventChanged(); 
}

Invoke the client listener when the event model's phase changes:

Assets/SharedCode/Events/ThemeEvent.cs

public partial class ThemeEventModel : PlayerLiveOpsEventModel<ThemeEvent, PlayerModel>
{
    protected override void OnPhaseChanged(PlayerModel player, LiveOpsEventPhase oldPhase, LiveOpsEventPhase[] fastForwardedPhases,
        LiveOpsEventPhase newPhase)
    {
        player.ClientListener.ThemeEventChanged();
    }
}

Lastly, implement the client listener and hook up the UI to enable/disable the theme when the phase changes:

Assets/Scripts/Metaplay/MetaplayService.cs

public partial class MetaplayService : IPlayerModelClientListener
{
    public static Action NotifyThemeEventChanged;

    public void ThemeEventChanged()
    {
        NotifyThemeEventChanged?.Invoke();
    }
}

Assets/Scripts/GameManager/LoadoutState.cs

void OnEnable()
{
    MetaplayService.NotifyThemeEventChanged += RefreshThemeUI;
}

void OnDisable()
{
    MetaplayService.NotifyThemeEventChanged -= RefreshThemeUI;
}

Create a New Game Event

With the events implemented, you can now use the LiveOps Dashboard to create and manage them.

Restart the local server with metaplay dev server.
Visit the LiveOps Events page on the dashboard.
Press New LiveOps Event.
Select the ThemeEvent, fill in a name, and optionally set a schedule and/or segment for targeting. Save the event.
If your schedule is currently active and your player is in the segment, the game will now show that the night theme is available.

Recap

We have now implemented Metaplay's game configs and used it to power the segmentation, experiments and LiveOps events features. At this point, our game is over-the-air configurable and ready for a more complex LiveOps workflows without client updates.

We could stop the tutorial here and focus on expanding the new systems we've implemented. However, we will continue with one more chapter to add a bit of polish to the game that makes it more interesting to look at.

Getting Started

New Game

Existing Game

Sample Projects

Wordle

Orca

SDK Updates

Release Notes

Release 34

Release 33

Release 32

Release 31

Release 30

Release 29

Release 27

Release 25

Open Source Software Licenses

Tutorial: LiveOps Features

Overview

SDK Features Quick Reference

Start Using Game Configs

Preparation

Implement Game Configs

Build & Publish in Unity Editor

Optional: Modify the Game Config

Implement Segmentation

Implement Player Properties

Optional: Inspecting Segments in Action

Create Experiments

Add Experiments to Game Configs

Managing Experiments

Implement LiveOps Events

Create an Event in Shared Code

Update the In-Game UI

Create a New Game Event

Recap

New Game

Existing Game

Wordle

Orca

Release Notes

Release 34

Release 33

Release 32

Release 31

Release 30

Release 29

Release 27

Release 25

Tutorial: LiveOps Features

Overview ​

SDK Features Quick Reference ​

Start Using Game Configs ​

Preparation ​

Implement Game Configs ​

Build & Publish in Unity Editor ​

Optional: Modify the Game Config ​

Implement Segmentation ​

Implement Player Properties ​

Optional: Inspecting Segments in Action ​

Create Experiments ​

Add Experiments to Game Configs ​

Managing Experiments ​

Implement LiveOps Events ​

Create an Event in Shared Code ​

Update the In-Game UI ​

Create a New Game Event ​

Recap ​

Overview

SDK Features Quick Reference

Start Using Game Configs

Preparation

Implement Game Configs

Build & Publish in Unity Editor

Optional: Modify the Game Config

Implement Segmentation

Implement Player Properties

Optional: Inspecting Segments in Action

Create Experiments

Add Experiments to Game Configs

Managing Experiments

Implement LiveOps Events

Create an Event in Shared Code

Update the In-Game UI

Create a New Game Event

Recap