Key Concepts

• Project Config File is the project-specific metaplay-project.yaml that contains the core configuration for your project.

Overview

Your project stores its core configuration in a file called metaplay-project.yaml, located at the the project root directory.

The contents look something like this:

metaplay-project.yaml

# Configure schema to use.
# yaml-language-server: $schema=../../MetaplaySDK/projectConfigSchema.json
$schema: "../../MetaplaySDK/projectConfigSchema.json"

# Configure project.
projectID: lovely-wombats-build
buildRootDir: .
sdkRootDir: MetaplaySDK
backendDir: Backend
sharedCodeDir: UnityClient/Assets/SharedCode
unityProjectDir: UnityClient

# Specify .NET runtime version to build project for, only '<major>.<minor>'.
dotnetRuntimeVersion: "9.0"

# Specify Helm chart versions to use for server and bot deployments.
serverChartVersion: 0.8.0
botClientChartVersion: 0.4.2

# Customize Metaplay features used in the game.
features:
  # Configure LiveOps Dashboard.
  dashboard:
    useCustom: true
    rootDir: Backend/Dashboard

# Project environments.
environments:
  - name: Develop
    humanId: lovely-wombats-build-quickly
    type: development
    stackDomain: p1.metaplay.io

Update Environments

You can update the environments specified in the metaplay-project.yaml using the CLI:

MyProject$ metaplay update project-environments

This fetches the environments from the Metaplay Portal and then updates any changed and adds missing environments to the metaplay-project.yaml.

The CLI command does not remove any deleted environments from the file. You can remove environments manually if they are no longer needed.

Upgrade Helm Charts

To upgrade the version of your Helm chart, you can just bump the version number of the chart to the desired version, for example:

# Specify Helm chart versions to use for server and bot deployments.
serverChartVersion: 0.7.1 // [!code --]
serverChartVersion: 0.8.0 // [!code ++]
botClientChartVersion: 0.4.2

The new version of the charts are advertised in release notes and will also be shown in the server logs and the LiveOps Dashboard.

Specify .NET Runtime Version

The .NET runtime version used in the container image builds is specified with:

# Specify .NET runtime version to build project for, only '<major>.<minor>'.
dotnetRuntimeVersion: "9.0"

If you want to upgrade to a more recent .NET version, you need to:

1. Bump the version in metaplay-project.yaml to the new version.
2. Upgrade all your C# project files (*.csproj) to target the desired framework, e.g.: <TargetFramework>net9.0</TargetFramework>
3. Fix any issues from the upgrade process itself, if there are any.

Read more at Microsoft's .NET upgrade guide.

Use Custom Authentication Provider

Availability

Using 3rd party authentication providers is only supported for self-hosted stacks. On Metaplay managed cloud, all environments use Metaplay Portal as authentication provider.

To use a 3rd party authentication provider with the CLI, you can configure it in the metaplay-project.yaml:

# Authenticate to project using Auth0.
authProviders:
  idler-auth0:
    name:             Idler Auth0
    clientId:         ktWZITsg0huCvRt3JMFXyR6x4uAWszAK
    authEndpoint:     https://metaplay.auth0.com/authorize
    tokenEndpoint:    https://metaplay.auth0.com/oauth/token
    userInfoEndpoint: https://metaplay.auth0.com/userinfo
    scopes:           openid profile email offline_access
    audience:         managed-gameservers

# Configure some environments to use the provider (they default to use the Metaplay Portal):
environments:
  - name: d1
    humanId: idler-develop
    type: development
    stackDomain: d1.metaplay.io
    serverValuesFile: Backend/Deployments/test-server.yaml
    authProvider: idler-auth0 # use idler-auth0 configured above

Note: The CLI supports multiple simultaneous sessions using different authentication providers. The authProvider.name is used to keep the sessions separate.

Add Custom Helm Values File

You can configure the deployments further by providing a custom Helm values file for the game server and bot client deployments.

See Configuring a Deployment for details.

MetaplayCoreOptions

The MetaplayCoreOptions allows you to configure core SDK options specific to your game. These options include project identification, supported client logic versions, default language settings, and feature flags for enabling or disabling specific SDK functionalities. The core options are essential for tailoring the SDK to meet the requirements of your project.

This configuration is found in the GlobalOptions.cs added during the SDK integration.

Assets/SharedCode/GlobalOptions.cs

public class GlobalOptions : IMetaplayCoreOptionsProvider
{
    /// <summary>
    /// Game-specific constant options for core Metaplay SDK.
    /// </summary>
    public MetaplayCoreOptions Options { get; } = new MetaplayCoreOptions(
        // Technical name for the project. Use only alphanumeric characters, underscores, and dashes.
        // Defaults to the project ID. Do not change!
        projectName:            "lovely-wombats-build",
        // The range of client logic versions that the server accepts connections from.
        supportedLogicVersions: new MetaVersionRange(1, 1),
        // The logic version of the current client.
        clientLogicVersion:     1,
        // Salt for generating guild invite codes.
        guildInviteCodeSalt:    0x17,
        // List of namespaces that contain shared game code logic.
        sharedNamespaces:       new string[] { "Game.Logic" },
        // Default language used by the game.
        defaultLanguage:        LanguageId.FromString("en"),
        // Configure enabled SDK features, such as localizations, guilds and leagues.
        // See MetaplayFeatureFlags for the full list.
        featureFlags: new MetaplayFeatureFlags
        {
            EnableLocalizations = false
        });
}

Further Reading

Here are some links to more advanced configuration that may be useful:

• Getting Started with Cloud Deployments helps you set up your CI build and deploy pipelines for the game server.
• Configuring Cluster Topology describes how Metaplay clustering works and how to work with it.
• Developing the LiveOps Dashboard helps you get started with customizing the LiveOps Dashboard for your game.