Metaplay Docs

Appearance

Introduction to Game Configs

Metaplay's game configs are a data-driven way to specify the game's design economy, and localization data using external tools like Google Sheets and Excel.

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.

Game configs workflow overview.

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.

Example of game configs for the example Idler project.

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 #keyDamageHitPointsSpeed...
Soldier101001.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 #keyDamageHitPointsSpeed
Soldier101001.5
Ninja501505.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.

Packaging of Game Config Archives.

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.

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 #keyDamageHitPointsSpeed
Soldier101001.5
Ninja501505.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
C#
// 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 ​

To build the game configs from Unity, open the Config Builder and click BuildGameConfig.

Build your new config by accessing Config Builder → Build Game Config.

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. Publishing Configs ​

You can trigger the uploads through code or using custom editor scripts. Take a look at this example:

C#
// Publish to local server.
[MenuItem("MyGame/Publish GameConfig/To local server", isValidateFunction: false, priority = 210)]
public static async Task PublishGameConfigToLocal()
{
    ConfigArchive configArchive = ConfigArchive.FromFile(GameConfigBuilder.StaticGameConfigPath);
    await GameConfigBuildUtil.PublishGameConfigArchiveToServerAsync("http://localhost:5550/api/", configArchive, authorizationToken: null, confirmDialog: false);
}

// Publish to a remote server.
[MenuItem("MyGame/Publish GameConfig/To develop", isValidateFunction: false, priority = 210)]
public static async Task PublishGameConfigToDevelop()
{
    ConfigArchive configArchive = ConfigArchive.FromFile(GameConfigBuilder.StaticGameConfigPath);
    EnvironmentConfig envConfig = DefaultEnvironmentConfigProvider.Instance.GetEnvironmentConfig("develop");
    string authorizationToken = await envConfig.FetchAuthorizationTokenAsync();
    await GameConfigBuildUtil.PublishGameConfigArchiveToServerAsync(envConfig.ClientGameConfigBuildApiConfig.AdminApiBaseUrl, configArchive, authorizationToken, confirmDialog: true);
}

You'll need an authorizationToken to publish your Game Config Archives to a server other than localhost. Take a look at Idler's code to see an implementation of how to use different token providers like Google and OAuth2.

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:

This game has two uploaded game configs.

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

Naming configs makes it much easier to keep track of them later.

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.

Publish a config to push it out to players.

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:

C#
[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:

C#
[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:

C#
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:

C#
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 the compiler throws 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:

C#
// Suppose you were debugging which Config Items are built during the Configs build process
public string DebugDescription => $"Adding {(TroopKind)Kind?.KeyObject} troop to archive.";
text
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.

C#
// 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.

Further Reading ​

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