Configuring Rich Presence strings
This topic describes how Rich Presence strings are configured.
Strings
For your Rich Presence strings, you must define the string-sets. We recommend that you give each string-set a friendly name to use as an identifier.
Each string-set that you create must contain a group of strings that are localized appropriately for the locales that the game will be released in.
In addition to the localized strings, you must also supply a culture-neutral string. This string is used if a request is made for a locale that isn't given.
Each string-set can also use in-game data by parameterizing the strings to further enhance them. A string-set can have as many parameters as you want, as long as the resulting strings don't exceed the character limits. For more information, see Policies and limits for Rich Presence strings.
Enumerations
The enumerations that are described as follows are defined through the events from Xbox Live Player Data.
Statistics
You can use numerical statistic values in your Rich Presence strings. For example, in a shooter game, you might want the Rich Presence string to show how many kills the player currently has.
The configuration just needs to show that the parameter should be replaced by the "Kill Count" statistic. It was created through the Common Schema Eventing system and is being passed or forwarded to the Xbox Live Player Stats service to be turned into Player Data. The statistic must be defined by using statistics configuration.
When the string is read by another player, the Rich Presence service retrieves the most up-to-date value for the "Kill Count" statistic. As a result, the string is always up to date.
State
You can also choose to use statistics that represent actual state values in your Rich Presence strings. For example, in a racing game, you could use a Rich Presence string to show which car the player is currently driving, or which map or track that the player is racing on.
You can configure state information by using the following two steps.
Define enumerations for any in-game strings. For example, if you have five maps in your game and you want those maps to be part of your Rich Presence strings, the five maps also need to be enumerated into localized strings.
Link the enumerations to statistics. The Rich Presence service again retrieves the most up-to-date value from Player Data by looking up the value of the statistic. It then determines which enumeration value that the statistic translates to.
Example game
For the rest of the example, suppose that you're working on the latest bucket-kicking game. You want to create a statistic for each type of bucket kicked and display the statistics by using Rich Presence strings.
Suppose the game rules are the following:
Bucket types are wooden, silver, and golden.
Locations are the mountains, the desert, and the beach.
When a bucket is kicked, it shatters. You must always search for more buckets.
Some buckets require special gear to successfully kick them. For example, you need a boot strong enough to withstand a kick.
The game has a multiplayer mode. If enough players are trying to kick a bucket at the same time, you don't need a particular boot.
Rich Presence string configuration looks like the following for this game.
Configuring statistics for Rich Presence
To use a statistic that's generated by Xbox Live Player Data in your Rich Presence strings, the Rich Presence service needs to know the names of the statistics.
Enumeration configuration example
Here's an example of defining a couple of enumerations.
Create an enumeration for the maps in the game. The game has three maps. They each get a friendly name so that they can be easily referred to.
For each locale, create a localized string for that map name. Notice that there's an overall default localization and one that's culture-neutral.
Consider the three weapons in the game. They have friendly names and localized strings. This for all the enumerations.
| Enumeration | Related statistic | Friendly name | Locale | String |
|---|---|---|---|---|
| Map | CurrentMap | Map_Mountains | Default | Mountains |
| en | Mountains | |||
| en-US | Mountains | |||
| en-GB | Mountains | |||
| de-DE | Gebirge | |||
| Other locales | ||||
| Map_Desert | Default | Desert | ||
| en | Desert | |||
| en-US | Desert | |||
| en-GB | Desert | |||
| de-DE | Wuste | |||
| Other locales | ||||
| Map_Beach | default | Beach | ||
| en | Beach | |||
| en-US | Beach | |||
| en-GB | Beach | |||
| de-DE | Strand | |||
| Other locales | ||||
| Boot | CurrentWeapon | Boot_Light | Default | Light |
| en | Light | |||
| en-US | Light | |||
| en-GB | Light | |||
| de-DE | Leicht | |||
| Other locales | ||||
| Boot_Medium | Default | Medium | ||
| en | Medium | |||
| en-US | Medium | |||
| en-GB | Medium | |||
| de-DE | Mittel | |||
| Other locales | ||||
| Boot_Strong | Default | Strong | ||
| en | Strong | |||
| en-US | Strong | |||
| en-GB | Strong | |||
| de-DE | Stark | |||
| Other locales |
String configuration example
Now that the enumerations and statistics have been defined, you can create your strings.
In the following example table, the first column is a friendly name to help with referencing one string-set versus another. In this example, the string "playingMap" is used for the first string-set, "totalKicked" for the second, and "multiplayer" for the third.
Locale-string pairs
The next two columns go in together. They're the locale-string pairs for the Rich Presence string.
In the first example, the string "Playing on {0}" in English is used. The {0} token is replaced by a value.
The string is then localized for other locales.
Just as in the enumerations, there must be a default string and culture-neutral strings. They're used when a player uses a locale that you haven't specified a locale-string pair for. The locales that are used for enumerations must match the locales for your strings.
Parameters to construct a string
The last column is for the parameters that are used to fill in the blanks in the Rich Presence string.
If you want the Presence service to look up the value of the parameter in the Statistics service, you must use the statistics name to refer to the parameter here. Using statistics in your strings lets you set them once. You don't have to rewrite them.
If your string has the map name in it, and you're using the CurrentMap statistic to fill in the blank, the Rich Presence service updates your string appropriately as your players travel from map to map in the game.
If you don't use statistics in your Rich Presence strings, no parameters can be specified.
In the following example table, use the current map that's generated by statistics in the first string. Use the BucketsKicked statistic in the second string.
The third example doesn't include parameters. The string is defined on its own; it doesn't refer to statistics.
| Friendly name | Locale | String | Parameters |
|---|---|---|---|
| playingMap | Default | Playing on map:{0} | CurrentMap |
| en | Playing on map:{0} | ||
| en-US | Playing on map:{0} | ||
| en-GB | Playing on map:{0} | ||
| de-DE | auf Karte spielen: {0} | ||
| Other locales | |||
| totalKicked | Default | Kicked {0} Buckets! | BucketsKicked |
| en | Kicked {0} Buckets! | ||
| en-US | Kicked {0} Buckets! | ||
| en-GB | Kicked {0} Buckets! | ||
| de-DE | {0} Eimer getreten! | ||
| Other locales | |||
| multiplayer | Default | Playing multiplayer | |
| en | Playing multiplayer | ||
| en-US | Playing multiplayer | ||
| en-GB | Playing multiplayer | ||
| de-DE | Mehrspieler spielen | ||
| Other locales |
There's no limit on how many strings you can create, but you must have at least one string for your game.
BucketsKicked is just a number that's replaced in your string.
CurrentMap is an example of a statistic where the string comes from the enumeration.
When your game sets Rich Presence to one of these strings, use the configuration to know which parameters are needed.