All Collections
Portal Pages
Design | Gamification | XP Levels
Design | Gamification | XP Levels

Player levels & Level ups

John Harley avatar
Written by John Harley
Updated over a week ago


brainCloud’s Gamification features provide server-side support for Experience Points (XP) and Levels. These features build upon the Statistics APIs and a concept of Player Rewards.

  1. Expressing progress to next level up by way of percent is effective at motivating players and reduces the length of numbers your UI must display. 

  2. If your game has a tutorial or onboarding process, it is a good idea to pay completely fixed (non-random) amounts of XP for completing tasks within the tutorial so Design can trigger Level Up celebrations at specific points to make the player feel good about learning the game. 

  3. Since the smallest amount of XP that can be paid is 1, a good design scale for XP increments to level up is 100s, to 1,000s, to 10,000s. 


On the brainCloud Portal, you can manage experience points (XP) and levels, and reward the player for leveling up. A player’s XP starts at 0 and is incremented using methods of the Player Statistics service. A list of player XP levels can be read from the client using ReadXPLevelsMetaData().  

Setting up your XP Levels

  • Click the [Add Item] button with the plus icon.

  • Min Points - the minimum amount of experience required to be the current level. Your level rankings will automatically be sorted by this value.

  • Status Title - the visible name of level. Leave blank if your levels aren't named.

  • Facebook Action - if using Facebook, add the publish action.

Player Rewards

brainCloud provides the ability to reward your players on level app. Fill in any rewards that are applicable to your game.

  1. XP Rewards - additional XP the players may get from the level.

  2. Achievement - Any achievements that the level rewards.

  3. Virtual Currencies - Currencies the player is awarded from the level up.

  4. User and Global Statistics - And add any stats that change based on this level up.

  • Click [Save]

Choosing your Level Cap Behavior

There are three Level Cap options:

  • Unlimited: XP is earned without limit. Not Recommended. The risk of setting this option is: if additional levels are rigged later, Users that earned vast amounts of XP past your highest rigged level may receive multiple level-up dialogs as the system "catches up" to their XP value.  

  • Auto-Cap - Recommended: Will allow XP to be earned up to but not exceeding the highest level that is rigged. When you rig additional levels, users will resume earning XP to the new highest level. 

  • Specified Cap Level: XP is earned up to the specified level which is less than the highest level rigged. Use this option if you want to rig surplus levels than you plan on using, and then "unlock more levels" in an update.  

Writing the code

With your levels setup, you can now write the code need to give your player's experience.

In your client code

  • Add the brainCloud client to your app.

  • Pair the client with the dashboard.

  • Authenticate your user into brainCloud and check their current level.

  • Write custom game logic that would reward XP.

  • Call IncrementExperiencePoints to grant the player that XP.

  • Handle any additional game actions that should occur on level.

void Start() {
    // Unity
    GameObject go = new GameObject();
    _bc = go.AddComponent<BrainCloudWrapper>();
    _bc.WrapperName = _wrapperName; // optionally set a wrapper-name
    _bc.Init(); // extra data, such as: _appId, _secret and _appVersion, is taken from the brainCloud Unity Plugin.
    DontDestroyOnLoad(go); // keep the brainCloud game object through scene changes
    _bc.AuthenticateAnonymous((response, cbObject) =>
        var jsonMessage =
            (Dictionary<string, object>) BrainCloud.JsonFx.Json.JsonReader.Deserialize(response);
        var jsonData = (Dictionary<string, object>) jsonMessage["data"];
        var playerLevel = int.Parse(jsonData["experienceLevel"].ToString());
        // TODO handle any setup information your game requires around the player level

void CustomGameLogic(int playerLevel)
    // TODO write your custom game logic
    // i.e. PlayerWinsGameMatch();

    _bc.PlayerStatisticsService.IncrementExperiencePoints(250, (response, cbObject) =>
        var jsonMessage =
            (Dictionary<string, object>) BrainCloud.JsonFx.Json.JsonReader.Deserialize(response);
        var jsonData = (Dictionary<string, object>) jsonMessage["data"];
        var rewardDetails = (Dictionary<string, object>) jsonData["rewardDetails"];
        var newLevel = int.Parse(rewardDetails["experienceLevel"].ToString());

        if (playerLevel != newLevel)
            Debug.Log("Your now at level " + newLevel + "!");

Did this answer your question?