Configuration #

You can set configurations at the engine level or the SDK level.

Engine configuration #

Pragma Engine uses a list of configuration files at startup to define environment and connection details for each part of your game’s development and release cycle. Your configuration files are passed as a list of files read from disk. Pragma Engine periodically polls your configuration files for changes and reloads them without requiring you to restart the engine.

Configuration overrides and application #

With Pragma Engine you can define a list of common configuration files that are shared between all of your engine deployments. You can also define code-level defaults for development or production environments. To view your configuration files and environments, see the pragma-engine/platform/5-ext/config folder.

Pragma Engine applies configurations in order, starting with code-level defaults, then each YAML file provided left to right. When applying configurations, Pragma Engine merges ConfigMaps. You can choose to delete a ConfigMaps entry by setting the value of a key to NULL.

As a best practice, organize your YAML files with as little overlap as possible. Minimal overlap makes organizing sets of configurations per environment easier.

Dynamic configuration #

The platform periodically checks your config files for changes and reloads them if changes are found. If you’ve made changes that can’t be dynamically loaded, such as changing a database host, you must restart Pragma Engine.

Secret encryption #

For security, you should encrypt secret values such as API keys, passwords, and credentials before they are stored in your configuration files. You can use the Pragma Homebase API to encrypt and decrypt secret values in your environment before putting them in your configuration files.

All secrets must be encrypted and decrypted per shard. Shards use different encryption keys.

Encrypt #

1. Connect to the VPN using the *.ovpn file provided to you during onboarding.
2. Navigate to your Homebase API URL. For example: https://api.homebase.<studioname>.pragmaengine.com/.
3. Choose /secrets/encryptV1.
4. Enter the following values in the request body:
   1. shardId - The name of the shard you are encrypting a value for.
   2. titleId - The working title of your game that uses the secret.
   3. value - The secret you’re encrypting.

Your encrypted secret will appear below in the Responses section.

Decrypt #

1. Connect to the VPN using the *.ovpn file provided to you during onboarding.
2. Navigate to your Homebase API URL. For example: https://api.homebase.<studioname>.pragmaengine.com/.
3. Choose /secrets/decryptV1.
4. Enter the following values in the request body:
   1. shardId - The name of the shard you are decrypting a value for.
   2. titleId - The working title of your game that uses the secret.
   3. value - The secret you’re decrypting.

Custom service encryption #

To use encrypted values in your custom services, do the following:

• add an encrypted string to your service configuration Kotlin file
• add the getDecryptedValue function to your custom service
• add the encrypted values to your configuration file.

The following is an example of a service configuration Kotlin file with an encrypted string.

package pragma.account.config

import pragma.config.ConfigBackendModeFactory
        import pragma.config.EncryptedString
        import pragma.config.PluginConfig
        import pragma.settings.BackendType
        
class TwitchIdProviderConfig private constructor(type: BackendType) : PluginConfig<TwitchIdProviderConfig>(type) {
   override val description = "Twitch Id Provider configuration."
   
   var clientSecret by types.encryptedString("your app's secret key (provided by Twitch)")
   var clientId by types.string("your app's id (provided by Twitch)")
   
   ...
}

To decrypt the private key, use the getDecryptedValue function in your service.

var formData = parametersOf(
   "client_id" to listOf(config.clientId), "client_secret" to listOf(config.clientSecret.getDecryptedValue())
)

The following is an example configuration YAML file for the above encrypted values in the TwitchIdProvider service.

social:
  core:
  pluginConfigs:
    AccountService.identityProviderPlugins:
      plugins:
        Twitch:
          class: "pragma.account.TwitchIdentityProviderPlugin"
          config:
            clientId: "some client Id"
            clientSecret: "encryptedValue"
            redirectUri: "http://localhost:11000/v1/account/twitch-redirect"

SDK configuration #

There are several ways to set configuration values for the Pragma SDK using Unreal. The following options are listed in order of priority, with each option overriding the ones below it.

In most cases, these values can be overriden at runtime if the config is changed and reloaded on disk.

1. Code

   Set the members directly on the Pragma Runtime config.
2. Command line argument

   Specify a URL on the command line using the command "-Pragma<variable>=<value>"

   Example: -PragmaBackendAddress=http://127.0.0.1:10000

   Full list of command line overrides:

   • -PragmaIni=
   • -PragmaBackendAddress=
   • -PragmaPartnerBackendAddress=
   • -PragmaDebug= (only if not a UE_BUILD_SHIPPING)
   • -OverrideSocialProtocol=
   • -OverrideGameProtocol=
   • -OverrideSocialHost=
   • -OverrideGameHost=
   • -OverrideSocialPort=
   • -OverrideGamePort=
   • -PragmaProtocolType=
   • -PragmaPartnerProtocolType=
   • -PragmaPartnerSessionSocialAuthToken=
   • -PragmaPartnerSessionGameAuthToken=
3. Pragma.ini override (recommended)

   Note: This override will work in UE_BUILD_SHIPPING clients.

   You have three options for defining this config:

   • File: %RootDir%/Pragma.ini
   • File: %ProjectDir%/Config/Pragma.ini.
   • Command line: Use the -PragmaIni=my/path/Pragma.ini argument, but note you’ll need to specify the filename as well.
   • This keeps the config in a generic .ini file that is shipped alongside your game with no need to configure command lines per distribution platform.
   • It can also be defined at deploy time, which means you can use different values across different deploys with the same server or client binaries.

     Do not package a Pragma.ini file into the build or you will not be able to override it–the packaged version will always be used. Use the Game config to package the SDK config with the build.

4. Game.ini override

   Note: This override will not work in UE_BUILD_SHIPPING client builds.

   You can define this config in the file %ProjectDir%/Saved/Config/%Platform%/Game.ini.

5. Game.ini packaged into build

   You can define this config in the file %ProjectDir%/Config/DefaultGame.ini.

   This is a good way to set default values, but we recommend not putting internal URLs in here that may accidentally leak into a shipping build.