Get in Character with PlayFab
Whether building the next big MMO or a cool new platformer, characters are an excellent way to drive user engagement. Not everyone gets as attached to their in-game characters as the gang from "The Guild," but giving players a way to customize their experience helps build loyalty and replayability. And now it's even easier to integrate characters into your game, thanks to PlayFab's new set of full-featured API calls.
In the PlayFab API, a user can have as many (or few) characters as a game developer would like. Characters can either be granted to a user via an API call from a trusted endpoint such as a game server, or from within the game client itself via the inventory system. A character then becomes its own unique entity, tied to the user. Each character has its own inventory, virtual currency, and custom data attached.
The rest is up to your imagination! You can use characters and custom data in an endless number of ways: Build a set of character classes and let players choose, or let players build their own characters from scratch. Give characters cool titles when they hit certain achievements, or let them acquire additional skills or new gear after they level up. Players can dress their characters up, or give them elaborate backstories and you can even give characters individual passports showing where they've been in the game.
Here's the basics to get you started:
Anatomy of a character
At the most basic level, a character consists of the following:
| Field | Description | Example |
|---|---|---|
| Id | a unique PlayFab-assigned numeric string | 865A68ED2456 |
| Name | an alphanumeric string; not unique | Bob |
| Type | a string to classify the type of character; if granted from an item in inventory, this will be the item type id |
BlueWarrior |
These fields are provided in the client and server API calls which grants a character to the user. Once set, these fields are currently immutable for the lifetime of the character.
Custom information
Beyond the basics, developers can set any sort of descriptive information they would like as a set of key-value pairs stored on the character's unique ID. Similar to how unique data is stored on the user, this information can be set and retrieved from a set of client or server calls in the Character Data category. For example, to set a publicly viewable description of the character, a developer would use the following command to set the data:
POST https://[TitleID].playfabapi.com/Server/UpdateCharacterData
Content-Type: application/json;
X-SecretKey: <title_key_value>
{
"PlayFabId": "2039475",
"CharacterId": "98342357",
"Data":
{
"Description":
{
"Value": "a very strong blue warrior",
"LastUpdated": "2014-08-20T12:30:45Z",
"Permission": "Public"
},
},
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"code": 200,
"status": "OK"
}
The following command would then be used to retrieve that information:
POST https://[TitleID].playfabapi.com/Server/GetCharacterData
Content-Type: application/json;
X-SecretKey: <title_key_value>
{
"PlayFabId": "2039475",
"CharacterId": "98342357",
"Keys": [ "description" ]
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"code": 200,
"status": "OK",
"data":
{
"CharacterId": "3945734562",
"Data":
{
"Description":
{
"Value": "a very strong blue warrior",
"LastUpdated": "2014-08-20T12:30:45Z",
"Permission": "Public"
},
},
"PlayFabId": "2039475"
}
}
Custom data follows the same pattern for Character Data as it does for User Data: There is data that is both readable and writable by the client and server, data that can be read by the client and written by the server, and data that is hidden entirely from the client. Beyond these divisions, data can also be classified as public or private for all players across a title.
Inventory and Virtual Currency
Developers familiar with PlayFab will know that we have a robust system for managing virtual currency, purchases, and user inventory. These systems have all been extended to include characters as well! Now a developer can have separate virtual currency balances for each character owned by a player. Any existing virtual currency model already in the title can be granted to a character in that title using the Add and Subtract server APIs.
Once a character has purchased an item, it is linked both to the character and to the owning user. Thus an item may, at the game's discretion, be passed in between characters a user owns, or even up into the user's inventory. Otherwise, inventory management for characters is very similar to that of users. Items may be consumed or used as normal.
Statistics and Leaderboards
We at PlayFab love data, and so we are most excited about the ability to integrate characters into game leaderboards. Finally, a way to know if the person who plays the best tank really does also play the best healer! Leaderboards for characters are able to pivot in a variety of ways, to answer questions like: Which of my characters has the highest score? Who are the best mages in the game? Where among my friends does my character's level stand?
Right out of the box, all character leaderboards are able to optionally be pivoted based on the character's type. This makes it important to classify the characters in your game in a way that will make later data collection useful: Not too broad, and not too granular. Not only can we display all of the top scores for a game's characters, but we can also display all of the top scores for just one class of characters.
Example #1: This call will return a sorted list of all the scores for all characters in a game:
POST https://[TitleID].playfabapi.com/Client/GetCharacterLeaderboard
Content-Type: application/json;
X-Authentication: <user_session_ticket_value>
{
"StatisticName": [ "Score" ],
"MaxResultsCount": 3
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"code": 200,
"status": "OK",
"data":
{
"Leaderboard": [
{
"PlayFabId": "2039475",
"CharacterId": "9234992",
"CharacterName": "CoolDude",
"DisplayName": "MyUserName",
"CharacterType": "blue_warrior",
"StatValue": "1001",
"Position": "0"
},
{
"PlayFabId": "2039475",
"CharacterId": "3498722",
"CharacterName": "MysticDude",
"DisplayName": "MyUserName",
"CharacterType": "red_mage",
"StatValue": "900",
"Position": "1"
},
{
"PlayFabId": "88887475",
"CharacterId": "18838574",
"CharacterName": "StrongDude",
"DisplayName": "SomeoneElse",
"CharacterType": "blue_warrior",
"StatValue": "300",
"Position": "2"
}
}
}
Example #2: This call will return a sorted list of all the scores only for a certain type of characters:
POST https://[TitleID].playfabapi.com/Client/GetCharacterLeaderboard
Content-Type: application/json;
X-Authentication: <user_session_ticket_value>
{
"StatisticName": [ "Score" ],
"MaxResultsCount": 3,
"CharacterType": "blue_warrior"
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"code": 200,
"status": "OK",
"data":
{
"Leaderboard": [
{
"PlayFabId": "2039475",
"CharacterId": "9234992",
"CharacterName": "CoolDude",
"DisplayName": "MyUserName",
"CharacterType": "blue_warrior",
"StatValue": "1001",
"Position": "0"
},
{
"PlayFabId": "88887475",
"CharacterId": "18838574",
"CharacterName": "StrongDude",
"DisplayName": "SomeoneElse",
"CharacterType": "blue_warrior",
"StatValue": "300",
"Position": "1"
}
}
}
In summary
We hope that by providing developers with this new class of functionality that we can help them create more depth and complexity in their games. Character management has been one of our most-requested features, and we are happy to deliver on that functionality. We here in the PlayFab office are looking forward to playing against each other in the next generation of games built on our platform!
Got questions about implementing characters in your game? Have feedback about our offering? Got an idea that you'd love to see added to the feature set? Tell us about them in our developer forums. We'd love to hear from you!