Key Concepts

• Game Configs (or just Configs) specify the game’s configuration, design, and economy data. They are typically defined in CSV files or spreadsheets, but other sources are also supported.

Overview

The primary purpose of the Game Configs system is to extract the game's design, economy, and localization data so that it can be edited separately from the game's code, making it faster to work with and more accessible to developers with less technical backgrounds.

In this article, we'll exemplify how to set up a store item class in your Configs so you can later add said items through data only, without updating the code. Let's say that in your game's shop, you can purchase a set of items for a price in gold. Here are the initial set-up steps to make this game feature data-driven using Game Configs.

1. Modeling and adding the initial data.
2. Adding the new item class to the code.
3. Build the Configs.
4. Publish.

Game Configs should not be mutated in game logic!

Mutating the configs in the game logic can create non-deterministic behavior and unpredictable bugs, and even affect other players unintentionally. After the building stage, the configs should be read-only!

Modeling and Adding the Data

The first thing you have to do is figure out how to represent your shop items in your Configs. By default, we use Google Sheets, but you have other options, such as using other spreadsheet applications, reading from JSON or CSV, or even using Unity prefabs. For most cases, it's as simple as adding a column for each property you need and adding rows for every Config item. In this case, we have a column for each attribute we want our shop items to have, and we'll start with two bundles: a StarterBundle and a BowBundle.

We'll start by creating a new Google Sheets document, and renaming the default tab to ShopItems.

After we've done that, we can populate the spreadsheet with our rows and columns as follows:

Id #key	Cost	Items[0]	Items[1]	Items[2]
StarterBundle	25	Sword	Shield	LeatherArmour
BowBundle	50	Bow	10:Arrow

Adding Item Classes to the Code

After figuring out how the data will look on the spreadsheets, you need to add the equivalent class to your C# code. This class will be the template for an entire library, which means a collection of Config items that can be described using the same C# class, usually bundled in the same spreadsheet. This way, each library will have distinct columns for each class member, and you’ll have different libraries for each new C# Config class you add.

You can add new libraries to your Configs by implementing the IGameConfigData<> interface:

GameConfig.cs

// Unique string-like identifier type for ShopItems (see below)
[MetaSerializable]
public class ShopEntryId : StringId<ShopEntryId> { }

// Configuration data for an entry in the shop, identified by a ShopEntryId
[MetaSerializable]
public class ShopItem : IGameConfigData<ShopEntryId>
{
    [MetaMember(1)] ShopEntryId      Id;       // Unique kind (id) of shop entry
    [MetaMember(2)] int              Cost;     // The cost in gold
    [MetaMember(3)] MetaItemReward[] Items;    // The items the player receives upon purchase

    // Extract the key that uniquely identifies the shop entry
    public ShopEntryId ConfigKey => Id;
}

All that's left to do is to add the ShopItems to your Game Config, adding a new entry is as simple as creating a new property with the GameConfigLibrary<TKey, TItem> type and the GameConfigEntry attribute!

public class SharedGameConfig : SharedGameConfigBase
{
    ...

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

Building the Configs

Metaplay ships with a utility to build the Game Configs quickly and easily. You can open the window by clicking Game Config Build Window in the Metaplay toolbar menu.

To build the Configs just fill in a name and the URL to the Google Sheet that you created in step 1, and press build. You'll get a prompt to login with your Google account, to allow accessing the provided spreadsheet Url.

The Game Config Builder will take care of converting the data and nicely packaging it into a compressed file.

This will automatically load the new configs into the Unity editor. If you happen to be running the game client in offline mode, it will also hot-load the changes into the running game. Great for quick iteration!

The Metaplay SDK automatically updates the contents of SharedGameConfig and recursively updates any references in the active PlayerModel (or other models) to the updated Game Config item classes.

Publishing Configs

When running in offline mode, the latest built Game Config is always used, therefor publishing is not required. For localhost or any other environment, it is required.

Publishing is as simple as selecting the right environment and pressing publish. This will automatically upload the latest built game config to the environment of your choice, whether it be localhost or a deployed game server.

Making Config Changes Before Updating the Server

It's not possible to preemptively push Config changes to an environment before updating the server. However, you can build the Configs locally and push the generated mpa file to the source control in the branch where you're planning on deploying the update from. Then, when you deploy an update in that environment, the server will automatically pick up the new Config from the branch you are deploying.

Further Reading

Now that you've had a good introduction to the basics of working with the Metaplay SDK, you can feel free to explore the rest of the documentation and find out more about what Metaplay has to offer.

Here's some links to help you on your learning journey:

• If you want to dig a little deeper into the Configs system, the Working with Game Configs page has details about Config identifiers, serialization, and integrating the Configs system into the dashboard.
• In the above example, we're using a feature called MetaRewards. As the name implies, it helps you with giving rewards to users, they're automatically available in Player Mails and Broadcasts. Take a look at Implementing MetaRewards!
• Reference implementations are best found in the Idler sample, It's part of the Metaplay SDK package that you downloaded at the beginning of the Getting Started Guide.
• The Wordle tutorial is a three-part series that covers a more practical use of actions, the player model, and Game Configs, as well as threading some new ground with regard to server programming. You can find them in the Wordle Tutorial section. It's worth noting the guides build on top of each other, so we recommend you start with the first one: Tutorial: Game Logic.