< 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

• Achievement Rule Design 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

• Level Rule Design 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 Playlyfe 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

• Custom Rule Design API
• Custom Rule Admin 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:

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:

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:

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:

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:

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

Achievement Rule

Custom Rule