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, add an encrypted string to your service configuration Kotlin file, getDecryptedValue to your custom service, and the encrypted values to your configuration file.

The following is an example of a service configuration with an encrypted value.

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"