WARNING

Stub: This article is a stub and only contains a cursory overview of the topic. See the Idler example project for a complete reference.

Overview

Using Game Configs is split into two phases: building the Game Config Archive from source data as a preprocessing step, and importing the built Archive into the game at runtime. If you're not familiar with the Game Configs concepts, please read the Working with Game Config Data first. This page addresses the customization of the build steps for game-specific features.

Game Config Build Pipeline

• Outputs
  • FullGameConfig is the main output from the Game Config Build Pipeline. It can contain the game's configuration, economy, and other relevant data.
    • FullGameConfig consists of
      • SharedGameConfig contains the data visible to both the client and the server
      • ServerGameConfig contains the parts that are only visible to the server
    • The output artefacts is two Archives nested within each other:
      • Outer Archive contains both SharedGameConfig and ServerGameConfig — outputted by the Game Config Builder.
      • Inner Archive contains only SharedGameConfig — used to distribute to client devices via CDN.
  • Localizations are stored separately, in per-language files.
    • Localizations will likely be included within the GameConfig in the future.
• Build Steps Overview:
  • The builder class derived from the GameConfigBuild class is responsible for building the FullGameConfig Archive:
    • This class is userland code and can be modified as needed.
    • This class is optional, as the SDK comes with a default implementation that works out of the box for simple use cases.
    • The builder works on the server and can be invoked from the LiveOps Dashboard.
    • Game config build sources (e.g. Google Sheets, local files, etc.) can be configured.
      • Set GameConfigBuildParameters.DefaultSource (or additional custom Sources in a custom parameters type) when calling StaticFullGameConfigBuilder.BuildArchiveAsync.
      • Also pass appropriate IGameConfigSourceFetcherConfig to BuildArchiveAsync to concretely configure the build sources (e.g. specify spreadsheet ids or local directory paths).
      • Derive from GameConfigBuildIntegration and override GetAvailableBuildSources to make sources available in dashboard UI.
      • It's possible to define custom GameConfigBuildSource classes.
• Parsing Game Config Libraries.

The build process consists of the following steps, each of which are described in more detail below:

• Importing data from various sources such as Google Sheets, files on disk (typically CSV or JSON), Unity prefabs or animations, or any other data source that can be queried during the build phase.
• Validating the source data for any malformed contents (eg, missing or broken data).

• Parsing the input data into the generic game config syntax trees.
• Resolving of A/B test variants by combining the variant-specific overrides with the baseline item values.
• Parsing the syntax tree into C# classes. Parsing target can be either the final class or an interim source transform item.
• Optionally, transforming the data. Sometimes it's useful to parse the input data into an intermediary class, which is then converted to the final representation.
• Validation of the final output game config, both the baseline and any A/B variants that were declared.

Build Steps Details

• Potential data sources:
  • Fetching from Google Sheets (using the GoogleSheetFetcher class).
  • Importing local (or remote) files (eg, CSV or JSON).
  • Unity prefabs (can be useful when migrating existing projects to Metaplay).
  • Unity animations (can extract specific frames to allow synchronizing logic to animations).
  • HTTP or other network requests.
  • Any user-defined source.
• Main workhorse methods for parsing source data:
  • BuildGameConfigKeyValueStructure<TStructure>() parses simple key-value data from input SpreadsheetContent into a regular class
    • TStructure must derive from GameConfigKeyValue.
  • BuildGameConfigLibrary<TKey, TInfo>() builds a GameConfigLibrary<TKey, TInfo> from SpreadsheetContent and assigns it to the target Game Config.
  • BuildGameConfigLibraryWithTransform<TKey, TInfo, TSourceItem>() parses the input into a set of TSourceItems and then transforms them into TInfos using a user-defined conversion method, and then builds a GameConfigLibrar<TKey, TInfo> out of them.
    • Allow parsing into intermediate type, then convert to final type.
    • Useful when source data doesn't trivially map to the runtime data types.
• Handling tabular spreadsheet data:
  • SpreadsheetContent stores raw spreadsheet content with original row/column numbers (from CSV files or Google Sheets).
  • GameConfigHelper.ParseCsvToSpreadsheet() for converting CSV to SpreadsheetContent.
  • GoogleSheetFetcher returns SpreadsheetContent by default.

• Parsing:
  • TODO: Specifying environments with special columns.
  • TODO: A/B testing with special columns.
  • TODO: Parsers for user-defined types can be added by deriving from ConfigParserProvider. - Eg, different PlayerReward types are implemented here.
• Game Config Libraries can reference data from each other.
  • You can use a MetaRef<> reference to another Game Config Item and parser will resolve it.
  • Resolving works via the IGameConfigDataResolver interface (mostly an implementation detail).
• Storing raw data in Archive (eg, CSV or JSON data).
  • Store files as-is in archive, should mainly be used for legacy data during migrations.
  • Late parsing in SharedGameConfig.PopulateConfigEntries().
    • Potential issues with formats and culture-dependent parsing (binary format is better defined).
• TODO: Dealing with multiple environments.
• TODO: Specifying data for different Experiments (A/B testing).
• Typical steps in the process include some or many of the following:
  • Fetch data from a source like Google Sheets.
  • Extract specific keyframes from in-game animations.
  • Extract data from existing Prefabs (can be useful when migrating data from legacy systems).
  • Perform any game-specific transformations on the data.

Simplified Game Config Example

MyGameConfig.cs

// Shared Game Config: Visible to both client and server.
public class SharedGameConfig : SharedGameConfigBase
{
    // Metadata about languages supported by the game.
    [GameConfigEntry("Languages")]
    public GameConfigLibrary<LanguageId, LanguageInfo> Languages { get; private set; }

    // Information about game-specific things.
    [GameConfigEntry("TroopKinds")]
    public GameConfigLibrary<TroopKind, TroopInfo> TroopKinds { get; private set; }

    // Note: PopulateConfigEntries override is only needed if there are entries with a custom format.
    public override void PopulateConfigEntries(GameConfigImporter importer)
    {
        base.PopulateConfigEntries(importer);

        // ... Import some library in a custom manner ...
    }

    // Optional validation
    public override void BuildTimeValidate(GameConfigValidationResult validationResult)
    {
        base.BuildTimeValidate(validationResult);

        // ... Custom validation code that happens at config build time ...
    }
}

// Server Game Config: Only visible to the server.
public class ServerGameConfig : ServerGameConfigBase
{
    // Metadata about configured A/B experiments.
    // Note: this is used by the SDK and is not needed until you wish to integrate the A/B experiment feature.
    [GameConfigEntry(PlayerExperimentsEntryName)]
    public GameConfigLibrary<PlayerExperimentId, PlayerExperimentInfo> PlayerExperiments { get; private set; }

    // Include game-specific hidden information here
}

Simplified Game Config Build Source Definition Example

The example below enables game config building from the LiveOps Dashboard by providing the possible Google Sheets to build from.

MyGameConfigBuildIntegration.cs

public class MyGameConfigBuildIntegration : GameConfigBuildIntegration
{
    public override IEnumerable<GameConfigBuildSource> GetAvailableBuildSources(string sourceProperty)
    {
        if (sourceProperty == nameof(GameConfigBuildParameters.DefaultSource))
        {
            return new[]
            {
                new GoogleSheetBuildSource("Development sheet", "1wXKv4SPD7BZBwTRc7YfAU7oVjuWFDZZFbHZ8PKyCatM"),
            };
        }

        return base.GetAvailableBuildSources(sourceProperty);
    }
}

Simplified Game Config Builder Example

The example below shows how to override the game config build steps for a specific entry. This is only needed when the default build pipeline behavior needs to be replaced.

MyGameConfigBuild.cs

// Declare build parameters
[MetaSerializableDerived(1)]
public class MyGameConfigBuildParameters : GameConfigBuildParameters
{
    // Add game-specific build parameters here
}

// Declare a Game Config Builder with game-specific types as generic arguments.
public class MyGameConfigBuild : GameConfigBuildTemplate<SharedGameConfig, ServerGameConfig, MyConfigBuildParameters>
{
    // GetEntryBuilder can override the default building behavior per config entry (i.e. library or GameConfigKeyValue).
    protected override ConfigEntryBuilder? GetEntryBuilder(Type configType, string entryName)
    {
        // Custom handling when needed for specific libraries.
        if (configType == typeof(SharedGameConfig) && entryName == "SomeLibrary")
        {
            // TODO: flesh out this example
            return CustomEntryBuildSingleSource<List<IGameConfigData>>(
                fetchFunc: GetGenericFetchFunc("SomeLibrary", BuildParameters.SomeCustomSource),
                buildFunc: (IGameConfigBuilder shared, List<IGameConfigData> items) =>
                {
                    List<VariantConfigItem<SomeId, SomeInfo>> variantItems = ... produce VariantConfigItems from items ...;
                    shared.AssignLibraryBuildResult("SomeLibrary", variantItems, sourceMapping: null);
                });
        }

        // Default behavior should typically work for most entries
        return base.GetEntryBuilder(configType, entryName);
    }
}

Parsing Custom Types with ConfigParser

// This example registers custom parsers for the game-specific types `PlayerReward`
// and `PlayerPropertyId`. This can be done by inheriting from the `ConfigParserProvider`
// class and implementing its `RegisterParsers()` method. Metaplay automatically detects
// the inheriting classes.
public class ConfigParsers : ConfigParserProvider
{
    // Register custom parsers for use in GameConfigBuilder
    public override void RegisterParsers()
    {
        ConfigParser.RegisterCustomParseFunc<PlayerReward>(ParsePlayerReward);
        ConfigParser.RegisterCustomParseFunc<PlayerPropertyId>(ParsePlayerPropertyId);
    }

    // Custom parser for PlayerReward type. Useful for specifying contents of
    // IAP packs, rewards from events, and anything else that the player can gain
    // as a result of playing the game.
    static PlayerReward ParsePlayerReward(ConfigLexer lexer)
    {
        int     amount      = lexer.ParseIntegerLiteral();
        string  rewardType  = lexer.ParseIdentifier();

        switch (rewardType)
        {
            case "Gems":
                return new RewardGems(amount);

            case "Gold":
                return new RewardGold(amount);

            default:
                throw new ParseError($"Unhandled PlayerReward type in config: {rewardType}");
        }
    }

    // Custom parser for PlayerPropertyIds, which are used to implement custom
    // segmentation rules for the players.
    static PlayerPropertyId ParsePlayerPropertyId(ConfigLexer lexer)
    {
        // First try builtin parsing in case it's an SDK-defined PlayerPropertyId type.
        if (ConfigParser.TryParseCorePlayerPropertyId(lexer, out PlayerPropertyId propertyId))
            return propertyId;

        // Game-specific PlayerPropertyIds.

        string type = lexer.ParseIdentifier();

        switch (type)
        {
            case "Gems":
                return new PlayerPropertyIdGems();

            case "Gold":
                return new PlayerPropertyIdGold();

            case "Producer":
            {
                lexer.ParseToken(ConfigLexer.TokenType.ForwardSlash);
                MetaRef<ProducerInfo> producer = ConfigParser.Parse<MetaRef<ProducerInfo>>(lexer);

                return new PlayerPropertyIdProducerLevel(producer);
            }

            case "LastKnownCountry":
                return new PlayerPropertyLastKnownCountry();

            case "AccountCreatedAt":
                return new PlayerPropertyAccountCreatedAt();

            case "AccountAge":
                return new PlayerPropertyAccountAge();

            case "TimeSinceLastLogin":
                return new PlayerPropertyTimeSinceLastLogin();
        }

        throw new ParseError($"Invalid PlayerPropertyId in config: {type}");
    }
}

Supported Builtin Types in Config Parser

The game config parser supports the following builtin types:

Type	Example(s)	Notes
int	5, -123	Other integer types can also be used
string	Some String	Quoted strings are supported for escaping characters
bool	true, True, FALSE	Case-insensitive
Enum	SomeEnumValue	Must be valid enum values
StringId	MyStr, com.example.iap_id	Maximum length is 1024
MetaRef<T>	MyStr, com.example.iap_id	Parsed as the key type of the config item type T
F32	-0.123, 32767.0	Signed 16.16 fixed point, with deterministic parsing
F64	1234567890.00000001	Signed 32.32 fixed point, with deterministic parsing
float	-0.111, 123456.123	32-bit floating point, WARNING: not deterministic!
F32Vec2 and F64Vec2	(1.23, 4.56)
F32Vec3 and F64Vec3	(1.23, 4.56, 7.89)
IntVector2	(123, 456)
double	-123.321	64-bit floating point, WARNING: not deterministic!
MetaTime	2022-12-25 12:34:56.789	year-month-day hour:minute:second . Either integer or fractional seconds.
MetaDuration	1d 12h 30m 15s	List of number-unit pairs (d=days, h=hours, m=minutes, s=seconds)
MetaCalendarDate	2022-12-25	Used for Schedule.Start.Date in activables
MetaCalendarTime	12:34:56	Used for Schedule.Start.Time in activables
MetaCalendarPeriod	1d 12h 30m 15s	Used for Schedule.Duration and other periods in activables' schedules. Same syntax as MetaDuration.
MetaActivableLifetimeSpec	Fixed 12h ScheduleBased Forever	Used for Lifetime in activables
MetaActivableCooldownSpec	Fixed 12h ScheduleBased	Used for Cooldown in activables
Nullable<T>		Either empty (for null) or same syntax as contained type
List<T>	See below	Either vertical (MyList[]), horizontal (MyList[0]), or single-cell comma-separated collection
T[]	See below	Either vertical (MyArray[]), horizontal (MyArray[0]), or single-cell comma-separated collection
Nested types	Member.SubMember	Can also parse into collection members (MyArray[0].Member)

Collection Syntax Examples

Examples of vertical collection syntax:

MyId #key	IntArray[]	Nested[].Name	...
FirstItem	10	First string
	20	Second string
	30
SecondItem	100	Only one string
	200

Examples of horizontal collection syntax:

MyId #key	IntArray[0]	IntArray[1]	IntArray[2]	Nested[0].Name	Nested[1].Name	...
FirstItem	10	20	30	First string	Second string
SecondItem	100	200		Only one string

Collections can also be represented in a single cell using a comma-separate list of values:

MyId #key	IntArray	...
FirstItem	10, 20, 30

There is also special case single-cell syntax [] for specifying an empty collection. This is useful for A/B variants to clear the baseline collection to an empty one. It can be combined with other collection syntaxes in the same sheet, but only one can be used for a single row.

/Variant	MyId #key	IntArray	IntArray[0]	IntArray[1]	...
	FirstItem		10	20
MyExperiment/MyVariant		[]

Advanced: Partial Game Config builds

The Idler Game Config build implementation supports incrementally updating only named entries in the currently active Game Config Archive. The Idler GameConfig Build window in the Unity editor contains controls for choosing which Game Config Entries to update.

When a partial build is triggered, the currently active Game Config Archive is fetched from the server as the basis of the build operation and only the chosen Google Sheets are fetched and imported on top of it. To protect from overwriting simultaneous edits to other parts of the Game Config, the server rejects publishing a partially built config if the currently active config has changed after the Game Config was built.

INFO

Partial building requires support from the Game Config build integration. Please speak to us if partial building would help your workflow!