Appearance
Appearance
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.
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!
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 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 Config item. In this case, we have a column for each attribute we want our shop items to have, and we'll start with 2 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 just 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 |
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:
// 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 ShopItem
s 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; }
}
Metaplay ships with a utility to build the Game Configs quickly and easily. To enable this window, navigate the Metaplay
menu in the Unity toolbar and click Enable Default Game Config Build Window
.
After this, 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.
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, be it localhost
or a deployed game server.
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: