Dependencies

• Metaplay overview - You should generally understand Metaplay works, so the configs are appropriately contextualized. Check out Introduction to Metaplay if you need a refresher!

Key Concepts

• A Game Config Item (or just Item) is a single configurable set of data representing one specific type of in-game element. It corresponds to a single row on a given Game Config Library sheet. An Item could be, for example, an enemy and its health and damage or a shop-exclusive item bundle, its price, and contents.
• A Game Config Library (or just Library) is a collection of Config Items, typically ones specified in the same spreadsheet.
• Game Config Archives are binary files in which the SDK packages all the config data. Archives are the atomic unit of transfer to clients using CDN.

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 be more accessible to developers with less technical backgrounds. This article explains everything you need to know to get started using it in your game.

You can iterate on the game design data in a tool of your choosing (e.g., Google Sheets) and publish new configs to the players over-the-air. You can also view your game config data using the LiveOps Dashboard.

INFO

Pro Tip! Game configs are a deep topic, and there are at least as many workflows as there are game studios. However, Metaplay SDK's game configs pipeline is highly customizable and extendable beyond the basics. Look at the Further Reading section at the end of this page for proper deep dives!

Config Items, Libraries, and Archives

The smallest unit of game config data is called a Game Config Item. Depending on how you like to model your game data, you could consider Items as individual objects in code or rows in a spreadsheet. Items can have as many properties as you like.

Kind #key	Damage	HitPoints	Speed	...
Soldier	10	100	1.5

Note that the columns that specify the item's identity must have the #key tag, e.g., Kind #key in this example. Items can also have multiple columns that make up the identity, e.g., a (Id, Level) tuple, in which case, both the colunms would have the #key tag.

You typically have collections of Items that make logical sense to group together, such as game items, heroes, cards, etc. We call them Game Config Libraries. Designers often prefer to make one spreadsheet tab per Library to keep the various Libraries and their Items neatly organized.

Kind #key	Damage	HitPoints	Speed
Soldier	10	100	1.5
Ninja	50	150	5.25
...

Finally, the SDK will package all your Libraries into binary files called Game Config Archives. They can be uploaded to a running server (either local or in the cloud) and published to game clients over-the-air without a separate client update or the need to reboot the game server.

Basic Use Case and Workflow

Let's say you have a game with idle combat in which you improve your army by buying some troops and other combat units. Here's an overview of the initial set-up steps to make a game feature data-driven via game configs.

1. Model and add initial data.
2. Add new Item class to shared code.
3. Build configs.
4. Publish configs.

Warning

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 parsing stage, the configs should be read only!

1. Model and Add Data

The first thing you have to do is figure out how to represent your troops in your configs. By default, we use Google Sheets, but you have other options like 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 Item. In this case, we have a column for each attribute we want our troops to have, and we have Soldier and Ninja as our troop types.

Kind #key	Damage	HitPoints	Speed
Soldier	10	100	1.5
Ninja	50	150	5.25

2. Add our Item Classes to Code

After figuring out how the data will look on the spreadsheets, you should add the equivalent class to your C# code. You might have already noticed, but this class will be the template for an entire Library. This way, each Library will have distinct columns for each class member, and you’ll have different Libraries for each new C# IGameConfigData<> class you add.

GameConfig.cs

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

// Configuration data for an in-game troop, identified by a TroopKind
[MetaSerializable]
public class TroopInfo : IGameConfigData<TroopKind>
{
    [MetaMember(1)] TroopKind Kind;       // Unique kind (id) of troop
    [MetaMember(2)] int       Damage;     // Damage dealt
    [MetaMember(3)] int       HitPoints;  // Hit points
    [MetaMember(4)] F32       Speed;      // Movement speed (a fixed-point value)

    // Extract the key that uniquely identifies the troop
    public TroopKind ConfigKey => Kind;
}

Implementing the IGameConfigData<> interface registers the type as a class containing a Game Config Item.

3. Building the Configs

Metaplay ships with a utility to build game configs quickly and easily, you can enable this window using the Metaplay/Enable Default Game Config Build Window menu item.

After this you can open the window using Metaplay/Game Config Build Window.

Building is quite simple, fill in a name and the url to the spreadsheet, and press build. We'll 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. This is great for rapid iteration.

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.

4. Uploading and Publishing Configs

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.

All uploaded game configs persist in the database along with their metadata. You can also view the complete history of game configs uploaded to the server in the game's LiveOps Dashboard on the Game Configs page:

There, you can also edit the name and description of the available Configs:

The default operation is to upload and publish the current Game Config Archive when calling PublishGameConfigArchiveToServerAsync. Still, it is also possible to only upload a new Archive to the server without publishing it. With this workflow, you can review your changes in the dashboard before setting them as active.

By default, each client will negotiate the version of the Game Config Archives to use upon connecting to the server. Incidentally, not all players will necessarily be using the same version of the configs, and you need to take that into account when programming interactions in a multiplayer game.

5. Iteration

After you set a Game Config Library, designers can iterate on it by editing the config data, adding Items in their preferred tool, and triggering the build step. You can also test it locally before publishing it to the server and setting it as active.

Advanced Topics

Game Config Item Identifiers

Each Game Config Item must have a unique identifier, extracted in the Item from the IGameConfigData<>.ConfigKey property. The SDK also uses this identifier to resolve references to any Items when deserializing data, e.g., when restoring player states from the database or sending messages or actions between the client and the server.

The default recommended way to identify a Game Config Item is to use a StringId:

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

[MetaSerializable]
public class TroopInfo : IGameConfigData<TroopKind>
{
    ...
    public TroopKind ConfigKey => Kind;
}

The StringId has some very convenient properties:

• First, it's human-readable, which always helps when debugging.
• It's type-safe: by default, the compiler only allows comparing StringIds to other StringIds of the same type. So, for example, you can only compare two TroopKinds against each other, but you cannot compare a TroopKind to an InAppProductId.
• It's stable in the source file/sheet: as long as the id remains the same, the deserializer can correctly identify any Item. Specifically, the row number on which the Item appears has no impact on its identity.
• The values are interned in the process memory, meaning that each value only exists once in the process. This makes storing and comparing the Items as efficient as using simple integers.
• Only ASCII characters are allowed. Furthermore, we recommend sticking to a C-like identifier subset for most use-cases, meaning alpha-numeric characters and underscores. Keeping to these characters makes parsing the values from inputs simpler to implement.
• Only a single non-existent value is supported, which is the StringId reference itself being null. Empty strings are not allowed as values, nor can the contained value be null.
• It's serialized as a string, both when persisting state into the database or communicating over the wire with the client.
• It has a maximum length of 1024 characters.
• All comparisons case-sensitive.

The StringId values should remain stable over the lifetime of a game. However, you will need to employ some form of migration in the case of renamed or removed identifiers. See section Handling Renamed Config Items in Working with Game Config Data for details.

INFO

Pro tip: It is also possible to use ints or strings as identifiers for Game Config Items, but this is discouraged since they lack the type safety that StringIds provide

Compound Identifier Types

You can also use compound types (structs and classes with multiple members) as ConfigKeys. Using them can be helpful, for example, when specifying per-level data in the source files/sheets. Check the Compound Identifier Types section in Working with Game Config Data.

Item References Inside Config Data

As described in Deep Dive: Data Serialization, when a reference to an IGameConfigData<TKey>-implementing class is serialized, only the ConfigKey property is serialized. When deserializing, the SDK uses the ConfigKey key to look up the Item in the appropriate Game Config Library. The PlayerModel (including its sub-models) and PlayerActions support such Game Config Item references. However, if game config data contains an Item reference within itself, it must be wrapped in the MetaRef<> type instead of a plain C# reference.

For instance, building on the example in the Example: Troop Types section, imagine that we further have a TroopGroupInfo config, with each TroopGroupInfo containing a list of troop types. Again, we want to express the list of troop types using references to TroopInfo Game Config Items instead of mere TroopKind values so that their existence gets validated (to guard against typos and such) when the game config is loaded.

TroopGroupInfo could be defined as follows:

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

[MetaSerializable]
public class TroopGroupInfo : IGameConfigData<TroopGroupId>
{
    [MetaMember(1)] public TroopGroupId             GroupId; // Unique id of group
    // Note: This has to use MetaRef<TroopInfo> instead of plain TroopInfo.
    [MetaMember(2)] public List<MetaRef<TroopInfo>> Troops;  // Troops in this group

    public TroopGroupId ConfigKey => GroupId;
}

The concrete reference within the MetaRef can be accessed via the Ref property:

public int TroopGroupTotalDamage(TroopGroupInfo groupInfo)
{
    int total = 0;
    foreach (MetaRef<TroopInfo> troopInfo in groupInfo.Troops)
        total += troopInfo.Ref.Damage; // Note: not "troopInfo.Damage"
    return total;
}

Or alternatively, using a helper extension from the SDK:

public int TroopGroupTotalDamage(TroopGroupInfo groupInfo)
{
    int total = 0;
    // MetaRefUnwrap gets the Ref for each element of the list,
    // decreasing verbosity in the rest of the loop.
    foreach (TroopInfo troopInfo in groupInfo.Troops.MetaRefUnwrap())
        total += troopInfo.Damage;
    return total;
}

It's important to note that a MetaRef is not resolved immediately upon deserialization but only when the client loads all of the Game Config Libraries. For this reason, you should only use the Ref property in contexts where it's certain the MetaRef has been resolved, or it'll throw an exception.

So, generally, when you implement methods or properties which can be accessed in any context (as opposed to ones you know you'll only access during normal game operation), you should not assume that the MetaRefs are resolved. However, if you only need access to a Config Item's key, you can use the MetaRef's KeyObject property, which does not need to wait for the Libraries to finish loading:

// Suppose you were debugging which Config Items are built during the Configs build process
public string DebugDescription => $"Adding {(TroopKind)Kind?.KeyObject} troop to archive.";

Adding Soldier troop to archive.
Adding Ninja troop to archive.
...

INFO

Note: A null Game Config Item reference is represented by the MetaRef variable itself being null. A MetaRef object instance always represents a non-null reference.

Configs Serialization

When the serializer parses a Game Config Item class like TroopInfo (see Basic Use Case and Workflow section), instead of writing out all the data within the Info class, only the ConfigKey property is serialized.

// Extract the key that uniquely identifies the troop
public TroopKind ConfigKey => Kind;

Similarly, when deserializing references to IGameConfigData<>, only the ConfigKey is deserialized and used to resolve the actual TroopInfo from the game's SharedGameConfig. This serialization/deserialization of the ConfigKey in place of the existing class members applies to serializing for sending over the network and persisting into the database. This keeps the serialized payloads smaller and, more importantly, allows changing the game config data without needing to update all the players in the database.

INFO

Good to know: The column names are automatically mapped to the member names in the TroopInfo class when importing the sheet or file. No custom parsing code is needed when adding new game config types to a game.

Using Key-Value Pairs in the Configs

You can create individual tweakable parameters in your configs using simple key-value pairs. Here's an example of a GlobalConfig that defines the players' starting gold and gems:

GlobalConfig.cs

[MetaSerializable]
public class GlobalConfig : GameConfigKeyValue<GlobalConfig>
{
    [MetaMember(8)] public int InitialGold { get; private set; } = 50;
    [MetaMember(9)] public int InitialGems { get; private set; } = 10;
}

You can define them in your configs source like so:

Member	Value
InitialGold	50
InitialGems	10

Later, declare your new key-value config somewhere in your SharedGameConfig.

SharedGameConfig.cs

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

You can find some more in-depth information about using key-value pairs in the configs in the Key-Value Pairs section.

Further Reading

After getting the basics of game configs down, here are some places you can go next:

• Tutorial: Game Logic - Get some hands-on experience writing game logic, including game configs.
• Localization - Localization configs mostly behave the same as design game configs, but some caveats warrant it having a separate page.
• Deep Dive: Data Serialization - Here, you can find more in-depth information about the serializer.
• Custom Game Config Build Pipelines - Finally, you can find out how to create custom config building pipelines.
• Game Config Archives - This page has in-depth information about subjects like Item identifiers handling renamed Game Config Items.