< Back to Manuals

Rules

A rule checks players for certain conditions and performs a specific action on the players if they satisfy those conditions. The action taken by the rule depends on its type.

Achievement Rules

An achievement rule awards a specific achievement to a player when they satisfy all the conditions.

Achievement rules are ideal for giving away badges (using set metrics) when the player meets certain conditions.
Achievement rules are evaluated everytime a player does some action.

It consists of 2 parts:

  1. Achievement - The achievement itself, which must be an item of a set metric. A player cannot receive an achievement if he already has it. An achievement rule does not remove an awarded achievement if a player fails any check at a future time.
  2. Requirements - A list of checks. A player must pass all checks to gain the Achievement.

You can use these conditions that while defining the achievement requirements:

Type Condition to select Description
Metric based condition If the player has the metric Metric based conditions can be used to check the value of a metric against a player's scores. E.g: A player with a certain badge or having score higher than 450, etc.
Action count based condition If an action has been triggered N times Action count based conditions check against the number of times the player has performed the specified action.
Aggregate conditions - All All of the following rules Various conditions can be combined by an AND condition.
Aggregate conditions - Any Any of the following rules Various conditions can be combined by an OR condition.

Use Cases

Apart from awarding achievements on certain conditions, you can organize achievement rules in complex hierarchies using checks. Each tier of achievements can check if the player was already awarded any achievements on the previous tier.

Related API

Level Rules

A level rule is used to determine the level of a player. The level rule basically changes the state of a player based on various thresholds on a given point metric.

A level rule has 3 parts:

  1. Base Metric - A point metric which is checked to determine the level to be assigned. The 'minimum' and 'maximum' constraints of the base metric determines the threshold value range.
  2. Level Metric - A state metric whose preset states represent the different levels.
  3. Levels - An ordered list of levels. Each level consists of a state and a threshold value. A player achieves a level when they cross the threshold for the previous level in the list.

Use Cases

You can create an experience based level system using level rules. You could also use them to show different reward tiers within a game.

Caution: Level rules only work if a player has a metric, so in case you want a player to have a certain level after creation, you might want to consider bootstrapping the base metric.

Related API

Custom Rules

Unlike the other two rules, where the rewards were fixed at either a set or a state metric, there are no such restrictions in a custom rule.

You can also do a lot more as they have variables that can be passed during runtime, which can be used to modify your conditions or rewards on the fly.

Lastly, they need to be triggered independently via an API call and can be applied on multiple players. You can have a look at our API documentation on custom rules for the details. To know more about how rewards are applied in custom rules, click here

A custom rule has 2 parts:

  1. Variables - Variables that can be passed in during runtime and can be used in conditions for rewards or in rewards themselves. Variables can be of 2 types - either strings or integers.
  2. Rewards - Rewards are a set of scores and conditions where the scores are given to a player if he satisfies the given conditions.

Use Cases

There might be scenarios where using an action might not be the right, specially for some ad-hoc tasks or accounting for some unexpected behaviour.

In a classroom model, you might be doing quizes and giving homework, both are a great fit for actions, but what if you want to give special rewards to those who have been consistent? You can create a custom rule that can be triggered every week to do this check.

Similarly, in sales teams, recording sales, leads, calls, etc are easy to do via actions. Now if you want to check if people have reached their targets or give out bonuses to those who exceeded them, custom rules can easily do the job.

Rewards in Custom Rules

Like mentioned earlier, there are no restrictions on the scores that can be given to players via custom rules. These scores will be given everytime a player satisfies the reward conditions and there is no concept of chance/probability in custom rules.

Conditions in custom rules are very similar to that of actions, here is the break down of the different kinds of conditions that can be put into place:

Type Condition to select Description
Metric based condition If the player has the metric Metric based conditions can be used to check the value of a metric against a player's scores. e.g., A player with a certain badge or having score higher than 450, etc.
Action count based condition If an action has been triggered N times Action count based conditions check against the number of times the player has performed the specified action.
Time based condition If the following timed condition is satisfied Time based conditions can be used to check against the time the action was performed. These comparisons are done taking into account the time zone of the game.
Formula Based If the following equation is satisfied We can use variables and player's scores in conditions. In this kind of condition, we can specify both the LHS and RHS of an equation.
Team based condition If the player is a part of the team Team based conditions are used to check against the player's role in a team.
Aggregate conditions - All All of the following rules Various conditions can be combined by an AND condition.
Aggregate conditions - Any Any of the following rules Various conditions can be combined by an OR condition.

Variables and Formula

With Custom rules, you get the option of sending variables at runtime. With these variables, the behavior of the rule can be modified at runtime.

These are the properties of variables that should be kept in mind while designing.

Variables allow users to input dynamic contents for evaluating rules when an action is performed. Each variable has the following properties:

Field Description
name The name of the variable.
type This is the type of the variable it can be a number or a string.
required Whether the variable is required when the player performs this action.
default The default value of the variable, which is applied only if the required property is not set.

Variables can be used in creating a formula, which in turn can be used in conditions and rewards.

Formula Based Conditions:

There are 2 ways we can have formula based conditions:

  1. Equation Based - Specify both the LHS and the RHS of an equation.

  2. Metric Based - The value of a metric as the LHS and an expression on the RHS.

Formula Based Scores:

Rewards can also have value that use a formula and let you vary rewards at runtime (Only available via API at the moment).

You are not restricted to simple expressions and can create more complex ones as per your requirement.

In any case (condition or scores) valid expression can be created using the following:

Type Referred As Description
Variables $vars

Runtime variables can be referenced in the formula as $vars.variable_name or $vars["variable_name"].

We recommend using the bracket syntax $vars[""], because if some variable names are invalid javascript identifiers, the condition would fail to execute properly if they are accessed with the dot (.) syntax $vars.

Variables can be either strings or integers.

Scores $scores

Player's scores can be referenced in a formula, however it is slightly different for different kinds of metrics.

In case of a point/compound metric, they can be referenced as $scores.metric_id and it will be replaced by the value of the metric.

In case of a set metric, in addition to the metric's ID, we would need the item name. It can be referenced as $scores.metric_id.item_name or $scores.metric_id["item_name"]. This will be replaced by the count of items of that type.

We recommend using the bracket syntax $scores[""], because if some metric ids are invalid javascript identifiers, the condition would fail to execute properly if they are accessed with the dot (.) syntax $scores.

Constants -

Only string or integer constants can be used in a formula. Integer constants can be used directly, but string constants need to be surrounded by "". viz. integer - 53, string - "53".

Scopes

Scopes let you create leaderboards for an arbitrary group of players. These are particularly useful when you want to create groups based on the source of an event.

Scopes are available only from Playoff API v2.0

Consider a class in which students are being offered various optional courses. Each course has quizzes which on completion grant rewards to the students. To maintain a leaderboard for any given course, instead of creating teams for each course, you can simply pass the course's name or any other unique identifier as the scope and a leaderboard for that course will be created on the fly. This leaderboard will only track actions or rules or processes that have been performed with the given scope.

Scopes are currently available only via API and are not available in the simulator.

Scopes would need a custom leaderboard in the design of the game. When executing an action, rule or task, you need to pass the scopes an array of objects with a keys id and entity_id. The id is the actual scope ID and the entity_id is the ID of the player who is being scored.

Related API

Design Structure

Base Structure

All rules have these common fields. Extra fields are required depending on what type of rule it is.

Field Description
id A unique ID for the rule.
name A name for the rule.
description Brief description of the rule.
type The type of rule. Can be one of level, achievement or custom. Achievement Rule Structure Level Rule Structure * Custom Rule Structure

Achievement Rule Structure

Achievement Structure

Field Description
metric This is the set metric a player will achieve if he statifies the requirements. Click here to see the metric structure.
items The items of the set metric that the player will gain. Each item will contain the properties Click here to see the item structure.
requires A set of conditions, based on which the achievement will be awarded to players. Click here to see the condition structure.

Achievement Metric Structure

Field Description
id The id of the set metric.

Achievement Item Structure

Field Description
key The name of the set item.
value Number of this item the player would gain.

Achievement Requirements Structure

This allows certain checks to be performed to make sure a player can actually see/perform/join the task, action, team.

Field Description
type The type of condition. It can be one of metric, action, team, and, or.
not If true, inverts the condition. So any check which would usually evaluate to true will now evaluate to false.
expression An array of contexts joined with an AND or OR operator. This field is only applicable if the condition type is and or or, and replaces the context field.
context The actual comparison expression. The structure changes depending on the type of condition selected. The structure for each condition is defined below:
  • metric - Metric Based Condition
  • action - Action Based Condition
  • team - Team Based Condition
The and and or type of conditions do not have this field. Instead, they have the expressions field, which is an array of these contexts.

Metric Based Condition

Condition which depends on a player's score for a particular metric

Field Description
id ID of the metric.
type Type of the metric being used for comparison.
For set metrics, there is an additional item field which denotes the set item
item The set item whose value will be compared.
This field is only available if the metric type is set.
operator Can be one of the relational operators:
  • eq (equal to),
  • ne (not equal to),
  • gt (greater than),
  • ge (greater than or equal to),
  • lt (less than),
  • le (less than or equal to)
value The value of the metric that the player should have on his scores.

Example:

{ "requires": { "type": "metric", "not": false, "context": { "id": "exp", "type": "point", "operator": "eq", "value": "55" } } }

Action Based Condition

Condition which depends on how many times an action has been performed.

Field Description
id ID of the action.
operator Can be one of the relational operators: eq, ne, gt, ge, lt, le.
value The number of times the action should be executed by the player.

Example:

{ "requires": { "type": "action", "context": { "id": "login", "operator": "eq", "value": "15" } } }

Team Based Condition

Condition which depends on how many times an action has been performed.

Field Description
definition_id Definition ID of the team which the player should be a part of.
role The role the player should have within the team of this type. If you don't care about the role, then you can ignore this field.

Example:

{ "requires": { "type": "team", "not": false, "context": { "definition_id": "disciples", "role": "student" // optional if the player can have any role } } }

All Conditions: and

An and condition, which is shown as All of the following rules can be used to join two or more conditions such that the whole condition will be true only when all of the child conditions are true.

Example:

{ "requires": { "type": "and", "expression": [ // two or more conditions ] } }

Any Condition: or

An or condition, which is shown as Any of the following rules can be used to join two or more conditions such that the whole condition will be true even if only one of the child conditions become true.

Example:

{ "requires": { "type": "or", "expression": [ // two or more conditions ] } }

Level Rule Structure

Field Description
base_metric This is the id of the point metric which you would be using to calculate the levels.
level_metric This is the id of the state metric which will supply the list of states to be used as levels.
levels This is an array of items, each item having one state item (from the level_metric) and the maximum threshold (base_metric) when that state item is applied to players. Click here to see the properties each item requires.

Level Rule Item Structure

Field Description
rank The name of the state you would like to assign.
threshold The max value of the base_metric (upper threshold) that is required by the player to gain this level. The lower threshold for each is determined as one more than the previous level's threshold. The lower threshold for the first level is hard-coded to -Infinity.

Custom Rule Structure

Rules

The rules that would be evaluated to give rewards to the player. This is an array consisting of objects with the fields rewards and requires.

Field Description
rewards The set of metrics that a player gets when he finishes this action. This is a an array consisting of one or more Rewards.
requires These are the conditions which are checked to see if the player is suitable to get this reward. For more information on requires, see the Requires Structure below.

Reward Structure

Field Description
metric

The metric which will be used for the reward. This is an object with two fields:

  • type: the type of the metric
  • id: The ID of the metric
verb Defines which operation is performed for this reward. Can be one of add, remove, set.
value The value by which the player's score changes.
probabilty The chance that this reward in an action or process task can be given must be within [0, 1] range.

Requires Structure

This allows certain checks to be performed to make sure a player can actually see/perform/join the task, action, team.

Field Description
type The type of condition. It can be one of metric, action, team, and, or.
not If true, inverts the condition. So any check which would usually evaluate to true will now evaluate to false.
expression An array of contexts joined with an AND or OR operator. This field is only applicable if the condition type is and or or, and replaces the context field.
context The actual comparison expression. The structure changes depending on the type of condition selected. The structure for each condition is defined below:
  • metric - Metric Based Condition
  • action - Action Based Condition
  • team - Team Based Condition
  • time - Timed Condition
  • var - Formula Based Condition
The and and or type of conditions do not have this field. Instead, they have the expressions field, which is an array of these contexts.

Metric Based Condition

Condition which depends on a player's score for a particular metric

Field Description
id ID of the metric.
type Type of the metric being used for comparison.
For set metrics, there is an additional item field which denotes the set item
item The set item whose value will be compared.
This field is only available if the metric type is set.
operator Can be one of the relational operators:
  • eq (equal to),
  • ne (not equal to),
  • gt (greater than),
  • ge (greater than or equal to),
  • lt (less than),
  • le (less than or equal to)
value The value of the metric that the player should have on his scores.

Action Based Condition

Condition which depends on how many times an action has been performed.

Field Description
id ID of the action.
operator Can be one of the relational operators: eq, ne, gt, ge, lt, le.
value The number of times the action should be executed by the player.

Team Based Condition

Condition which depends on how many times an action has been performed.

Field Description
definition_id Definition ID of the team which the player should be a part of.
role The role the player should have within the team of this type. If you don't care about the role, then you can ignore this field.

Timed Condition

You can also define conditions which become true only when triggered on a particular time.

Field Description
func The time unit to be counted, against a fixed duration. The available choices are:
  • hour_of_day
  • day_of_week
  • day_of_month
  • day_of_year
  • week_of_year
  • month_of_year
operator Can be one of the relational operators: eq, ne, gt, ge, lt, le.
value The count of the unit to be counted chosen in the func field. For example, for day of week, the value will represent day, and sensible values will be an integer between 1 to 7, both included.

Formula Based Condition

You can also setup equations with two sides, a left-hand expression (LHS), a right-hand expression (RHS) and an operator. Whenever the equation is satisfied, the condition becomes truthy.

Field Description
lhs An arithmetic expression, which can use other metrics or variables defined within the custom rules as components. An example: $scores.health + $vars.run_length
operator Can be one of the relational operators: eq, ne, gt, ge, lt, le.
rhs Another arithmetic expression, same as the lhs.

Variables

Variables allow users to input dynamic contents for evaluating rules when an action is performed. Each variable has the following properties:

Field Description
name The name of the variable.
type This is the type of the variable it can be a number or a string.
required Whether the variable is required when the player performs this action.
default The default value of the variable, which is applied only if the required property is not set.

Examples

Level Rule

{ "name": "Boost Levels", "id": "boost", "description": "The levels a player can rise up to based on experience", "type": "level", "base_metric": "experience", "level_metric": "levels", "levels": [ { "rank": "Level 1", "threshold": "15" }, { "rank": "Level 2" // if no threshold is specified it goes till Infinity } ] }

Achievement Rule

{ "name": "World Achievements", "id": "world_achivements", "description": "The achievements the player can gain within the world", "type": "achievement", "metric": { "id": "badges" }, "items": [ { "key": "Camper", "value": "1" } ], "requires": { "type": "action", "context": { "id": "login", "operator": "eq", "value": "15" } } }

Custom Rule

{ "name": "Course Rule", "id": "course_rule", "description": "This rule is excuted when a player completes a course", "type": "custom", "rules": [ { "rewards": [ { "metric": { "id": "experience", "type": "point" }, "verb": "add", "value": "10" } ], "requires": {} } ], "variables": [ { "name": "score", "type": "int", "required": true, "default": 0 } ] }