< Back to Manuals

Actions

Actions are an easy way of capturing events on the playoff platform.

Actions are basic triggers that allow you to translate player events/actions into a measurable entities on playoff.

An action has 3 parts:

  1. Rewards - Rewards are a set of scores and conditions where the scores are given to a player if he satisfies the given conditions.
  2. Variables - Variables that can be passed in during runtime and can be used in conditions for rewards or in rewards themselves.
  3. Visibility Requirements - By default, all actions are visible to all players. By using visibility requirements, you can restrict access to actions to only those players who satisfy a given criteria.

Use Cases

Any task done by a person can be easily recorded in playoff by using Actions. For example, an action could be going to the gym, reading a book, liking a facebook post or answering a quiz.

An action can be used pretty much anywhere. In case of an online education platform, action could be watching a tutorial video, which would fetch a player some experience points that can be used to show the person their progress within the course. Similarly, answering questions or posting on forums can also be actions that contribute to their progress or rating.

Rewards

Rewards are a set of metrics (points, badges, etc.) that a player gets when an action is performed. These rewards are metrics and can be either added, removed or set on a player.

Note: Adding negative values will reduce the player's score, similarly removing negative value increases the player's score.

Each reward can have its own conditions which are to be satisfied for the reward to be executed. More advanced scoring conditions such as probability and rate limits can also be set.

The various kinds of conditions available to you are:

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.
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.

Scoring Probability

A scoring probability (a.k.a chance) can be used to bring in an element of randomness or chance into the system. Scoring probability in actions can be set at 2 levels:

  1. Overall action level
  2. Per-reward level

A scoring probability at the action level would affect all the rewards of the action. It would be useful when you want to give all rewards together. The reward level probability would affect only a particular reward, hence you can control probabilities of each reward individually. Both probabilities can also be used simultaneously.

Rate Limiting

The default rate limit of an action is Infinity (i.e no rate limits), but if you want to rate limit an action you can specify the frequency limit. For example, an action can be set to execute at a maximum of 10 times per day.

There are 3 different types of rate limits that can be applied, they are:

  1. Rolling Window - A moving window type rate limit essentially means that at any given point in time, the activity can only be done a specified number of times in the last interval. Let us say your rate limit is 5 times per day, this would translate to a limit of 5 times in the last 24 hours (more precisely, in the last 24x60x60x1000 milliseconds) at any given point in time. Since we need to store timestamps for each event, there is a limit of 50 events in an interval. This is the default algorithm.

  2. Fixed Window - In a fixed window rate limit, the windows are fixed at particular time intervals - minutes, hours, days, weeks, months and years. What this means is that if your rate limit is 5 per day, the activity can be performed 5 times in a calendar day. In this alogirthm, the game's timezone is used to figure out calendar limits. The interval unit has been restricted only to 1 (i.e. 5 times in 1 day, in 1 minute, etc) as some other values can lead to unexpected results.

  3. Leaky Bucket - The leaky bucket algorithm, though generally used in the world of networking, might also find use in games. You can read more about it here.

Formula and Variables

Variables in actions can be defined to tweak the behavior of actions at runtime. Variables can be of 2 types - Strings and Integers. They can be used in both conditions and in rewards by creating a formula.

Here are some details on how variables and scores can be used in a formula:

Type Referenced As Description
Variables $vars Runtime variables can be referenced in the formula as $vars.variable_name.
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.

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 "". E.g: Integer - 53 String - "53"

Action Count

Actions can also be triggered with a count. This count basically acts as a multiplier for the action's rewards.

For example, in a gym app, running 1km is an action with reward of calories burnt 300, if you perform the same action with a count of 3, rewards would now be 900. This way you dont have to make 3 calls for an action or make a new action for a 3km run. The action count can only be an integer.

You can view our API documentation on actions to see how to actually use the action count.

Caution: In case when an action has an action count condition and depends on its own action count, the rewards are taken as per the initial action count before execution.

Visibility Requirements

Visibility requirements allow your action to be visible only to a certain type of players. The conditions can be specified in a similar fashion as the conditions in rewards, however some conditions are not available.

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.
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.

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/rules/processes that have been performed with the given scope.

Scopes are currently available only via API and are not available in the simulator and 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 the keys id and entity_id. The id is the actual scope ID and the entity_id is the ID of the player on whom the score will be applied.

Design Structure

Base Structure

Field Description
id A unique ID for the action.
name A name for the action.
description Brief description of the action.
image An image which represents the action. You need to send a multipart form POST request to upload the image data.
probability The probability that the player gets the rewards on completing the action.
rate

Rate Limiting an action so that users do not abuse the system.

This is an array of three items, which are:

  1. Count - The number of times the player can perform this action within the window.
  2. Timeframe - Counted in milliseconds, this is the window or timeframe within which the player can perform this action Count number of times.
  3. Type - The type of rate limiting being used, which can be one of rolling, fixed, leaky.

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.

Requires

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 ] } }

Examples

Action

{ "name": "Basic", "id": "basic", "description": "Get some experience", "rules": [ { "rewards": [ { "metric": { "id": "experience", "type": "point" }, "verb": "add", "value": "10" } ], "requires": {} } ], "requires": {} }

Action with Variables

{ "name": "Advanced", "id": "advanced", "description": "Get some experience based on score and probability", "probability": 0.7, "rules": [ { "rewards": [ { "metric": { "id": "experience", "type": "point" }, "verb": "add", "value": "$vars['score']", "probability": 0.5 } ], "requires": {} } ], "requires": {}, "variables": [ { "name": "score", "type": "int", "required": true, "default": 0 } ] }

Action with Rate-Limit

{ "name": "Thrash", "id": "thrash", "description": "Prevent a player from playing more than once a day", "rules": [ { "rewards": [ { "metric": { "id": "experience", "type": "point" }, "verb": "add", "value": "5" } ], "requires": {} } ], "requires": {}, "rate": [1, "day", "fixed"] }