Migrate v1.12.0 to v1.13.0

This guide provides a comprehensive overview of the structural changes implemented in the reward system with the update from v1.12.0 to v1.13.0. Developers utilizing the reward system via API or custom implementations are strongly advised to carefully review the changes outlined below and adjust their reward configurations accordingly to ensure seamless integration.

1. Core Structural Changes: Reward Bundle Evolution

v1.12.0: Legacy Reward Bundle Structure

In v1.12.0, reward configurations were relatively straightforward, with reward amounts directly embedded within the config object, specifically within TokenReward and RandomReward types.

"rewardBundle": {
  "rewards": [
    {
      "type": "TOKEN",
      "templateFields": {},
      "config": {
        "amount": 10
      },
      "visibility": "visible"
    },
    {
      "type": "GOLD_TROPHY",
      "templateFields": {},
      "config": {
        "path": "$.goldTrophy",
        "operation": "ADD",
        "dataType": "integer",
        "value": 1
      },
      "visibility": "promoted"
    }
  ]
}

v1.13.0: Enhanced Flexibility and Control

v1.13.0 introduces a refined reward structure, prioritizing flexibility and granular control over reward distribution. Key changes include:

• Dedicated amount Field: A new amount field has been added to support both fixed (const) and variable (range) values. This field did not exist in the root of the reward object previously, and was only present in specific reward types config.
• weight Field: A weight field has been added to control the probability of a reward being selected, enabling weighted reward distributions.
• Modifier Support: The introduction of modifiers enables complex reward distribution logic, such as allowing users to choose rewards or distributing rewards randomly.
• Standardized config.value: For PerkSlots, GoldTrophy, and FeaturedTrophy rewards, config.value should be set to 1 for compatibility.
• TokenReward and RandomPerk Adjustment: The config.amount field has been removed; amount is now directly in the amount field.

"rewardBundle": {
  "rewards": [
    {
      "type": "TOKEN",
      "templateFields": {},
      "config": {},
      "amount": {
        "type": "const",
        "config": {
          "value": 10
        }
      },
      "weight": 1,
      "visibility": "visible"
    },
    {
      "type": "GOLD_TROPHY",
      "templateFields": {},
      "config": {
        "path": "$.goldTrophy",
        "operation": "ADD",
        "dataType": "integer",
        "value": 1
      },
      "amount": {
        "type": "range",
        "config": {
          "min": 1,
          "max": 4
        }
      },
      "weight": 1,
      "visibility": "promoted"
    }
  ],
   "modifiers": [
    {
      "type": "CHOOSE_ANY",
      "config": {
        "amount": 1
      }
    },
    {
      "type": "GIVE_RANDOM",
      "config": {
        "rounds": 1
      }
    }
  ]
}

📘

For detailed information on the new amount and weight fields, please refer to the Reward Documentation.

2. Granular Amount Specifications

The amount field now supports two distinct types, providing enhanced flexibility:

• const: Specifies a fixed reward amount.

{
  "type": "TOKEN",
  "amount": {
    "type": "const",
    "config": {
      "value": 100
    }
  },
   "weight": 1
}

• range: Defines a reward amount within a minimum and maximum range, introducing dynamic reward distribution.

{
  "type": "TOKEN",
  "amount": {
    "type": "range",
    "config": {
      "min": 30,
      "max": 60
    }
  },
   "weight": 1
}

3. Introducing Modifiers: Enhanced Reward Control

CHOOSE_ANY Modifier

The CHOOSE_ANY modifier allows users to select a specified number of rewards from the available options.

{  
  "modifiers": [  
    {  
      "type": "CHOOSE_ANY",  
      "config": {  
        "amount": 1 // User can choose 1 reward  
      }  
    }  
  ]  
}

GIVE_RANDOM Modifier

The GIVE_RANDOM modifier distributes rewards randomly based on their defined weights. It is crucial to set a weight for each reward in the rewards array when using this modifier.

{  
  "modifiers": [  
    {  
      "type": "GIVE_RANDOM",  
      "config": {  
        "rounds": 1
      }  
    }  
  ],  
  "rewards": [  
    {  
      "type": "TOKEN",  
      "amount": { "type": "const", "config": { "value": 10 } },  
      "weight": 1  
    },  
    {  
      "type": "GOLD_TROPHY",  
      "amount": { "type": "const", "config": { "value": 1 } },  
      "weight": 0.5  
    }  
  ]  
}